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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +63 -11
  2. package/dist/cli.d.ts +2 -0
  3. package/dist/cli.js +90 -0
  4. package/dist/index.d.ts +7 -0
  5. package/dist/index.js +118 -0
  6. package/dist/options.d.ts +5 -0
  7. package/dist/options.js +46 -0
  8. package/dist/repo-docs.d.ts +33 -0
  9. package/dist/repo-docs.js +94 -0
  10. package/dist/schema-version.d.ts +10 -0
  11. package/dist/schema-version.js +19 -0
  12. package/dist/sidebar.d.ts +10 -0
  13. package/dist/sidebar.js +30 -0
  14. package/dist/site-options.d.ts +9 -0
  15. package/dist/site-options.js +39 -0
  16. package/dist/types.d.ts +47 -0
  17. package/dist/types.js +4 -0
  18. package/lib/{repo-docs.mjs → repo-docs.ts} +22 -46
  19. package/lib/{schema-version.mjs → schema-version.ts} +4 -9
  20. package/package.json +14 -8
  21. package/src/components/PlanInteractions.astro +15 -3
  22. package/src/components/board/Board.tsx +244 -0
  23. package/src/components/board/KanbanItemCard.tsx +129 -0
  24. package/src/components/board/LinkRuns.tsx +21 -0
  25. package/src/components/board/TaskKanbanCard.tsx +81 -0
  26. package/src/components/board/useBoardUrlState.ts +41 -0
  27. package/src/components/timeline/Timeline.tsx +159 -0
  28. package/src/components/timeline/useTimelineLayout.ts +39 -0
  29. package/src/env.d.ts +2 -2
  30. package/src/lib/board-data.ts +84 -0
  31. package/src/lib/board.ts +209 -0
  32. package/src/lib/planning.ts +66 -38
  33. package/src/lib/references.ts +1 -1
  34. package/src/lib/timeline.ts +156 -0
  35. package/src/loaders/repo-docs.ts +3 -3
  36. package/src/pages/plan/board.astro +14 -113
  37. package/src/pages/plan/roadmap.astro +20 -2
  38. package/src/scripts/plan.ts +3 -49
  39. package/src/styles/components.css +127 -10
  40. package/src/styles/kanban.css +277 -0
  41. package/src/styles/timeline.css +210 -0
  42. package/cli.mjs +0 -120
  43. package/index.d.ts +0 -49
  44. package/index.mjs +0 -97
  45. package/lib/options.mjs +0 -67
  46. package/lib/sidebar.mjs +0 -47
  47. package/lib/site-options.mjs +0 -38
@@ -0,0 +1,21 @@
1
+ // Prose with every known ID and brief path linked to its page: the island's
2
+ // LinkedText.astro. The runs are built at build time (board-data.ts).
3
+ import { Fragment } from 'react';
4
+
5
+ import type { LinkRun } from '../../lib/board';
6
+
7
+ export default function LinkRuns({ runs }: { runs: LinkRun[] }) {
8
+ return (
9
+ <>
10
+ {runs.map((run, index) =>
11
+ run.href ? (
12
+ <a key={index} href={run.href} title={run.label ?? undefined}>
13
+ {run.text}
14
+ </a>
15
+ ) : (
16
+ <Fragment key={index}>{run.text}</Fragment>
17
+ ),
18
+ )}
19
+ </>
20
+ );
21
+ }
@@ -0,0 +1,81 @@
1
+ /**
2
+ * TaskKanbanCard — Agile task card with priority labels, progress completion bar, and due date.
3
+ *
4
+ * From the Astro Components Kit by Konstantin (https://astrocomponents.dev/docs/task-kanban-card/,
5
+ * https://github.com/konstantinWDK/astro-components), MIT License. Ported to React from its
6
+ * manual-install source (via ../lib/TaskKanbanCard.astro); the changes are that hard-coded
7
+ * dark-theme colours use Starlight theme variables, so the card reads in light and dark themes;
8
+ * the task can be a link, for the site's item popup and backlinks (href, itemId), and a task that
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
+ * 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. Its styles are in src/styles/kanban.css.
12
+ */
13
+ import type { CardRag, LinkRun } from '../../lib/board';
14
+ import type { Size } from '../../lib/planning-types';
15
+ import LinkRuns from './LinkRuns';
16
+
17
+ interface Props {
18
+ task: string;
19
+ taskRuns: LinkRun[];
20
+ date: string;
21
+ /** Null with no owner: no chip, as the owner filter hides the card. */
22
+ assigneeInitials: string | null;
23
+ size: Size | null;
24
+ rag: CardRag;
25
+ progress: number;
26
+ href: string | null;
27
+ itemId: string | null;
28
+ }
29
+
30
+ const sizeVariant: Record<Size, 'low' | 'med' | 'high'> = { S: 'low', M: 'med', L: 'high' };
31
+
32
+ export default function TaskKanbanCard({ task, taskRuns, date, assigneeInitials, size, rag, progress, href, itemId }: Props) {
33
+ return (
34
+ <div className="task-card">
35
+ <div className="task-card__tags">
36
+ <span className="k-item__badges">
37
+ {size && (
38
+ <span className={`task-card__tag task-card__tag--${sizeVariant[size]}`} title={`Size ${size}`}>
39
+ <span className="task-card__tag-dot" aria-hidden="true"></span>
40
+ {size}
41
+ </span>
42
+ )}
43
+ {rag !== 'none' && <span className="k-item__rag" data-rag={rag} role="img" aria-label={`RAG ${rag}`}></span>}
44
+ </span>
45
+ <span className="task-card__pct">{progress}%</span>
46
+ </div>
47
+
48
+ <p className="task-card__desc">
49
+ {href ? (
50
+ <a className="plan-item-link" href={href} data-item={itemId ?? undefined}>
51
+ {task}
52
+ </a>
53
+ ) : (
54
+ <LinkRuns runs={taskRuns} />
55
+ )}
56
+ </p>
57
+
58
+ <div className="task-card__progress-wrap" role="progressbar" aria-valuenow={progress} aria-valuemin={0} aria-valuemax={100} aria-label="Task progress">
59
+ <div className="task-card__progress-bar" style={{ width: `${progress}%` }}></div>
60
+ </div>
61
+
62
+ <div className="task-card__footer">
63
+ <div className="task-card__date">
64
+ <svg className="task-card__date-icon" width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
65
+ <rect x="3" y="4" width="18" height="18" rx="2" ry="2"></rect>
66
+ <line x1="16" y1="2" x2="16" y2="6"></line>
67
+ <line x1="8" y1="2" x2="8" y2="6"></line>
68
+ <line x1="3" y1="10" x2="21" y2="10"></line>
69
+ </svg>
70
+ <span>{date}</span>
71
+ </div>
72
+
73
+ {assigneeInitials && (
74
+ <div className="task-card__assignee" title={`Assigned to ${assigneeInitials}`}>
75
+ {assigneeInitials}
76
+ </div>
77
+ )}
78
+ </div>
79
+ </div>
80
+ );
81
+ }
@@ -0,0 +1,41 @@
1
+ // The Board's filter and group state, kept in the page URL. The server has no
2
+ // location, so the first render is always DEFAULT_STATE (hydration must match
3
+ // it); the query is read in an effect on mount. Every later change is written
4
+ // back with history.replaceState, in boardQuery's fixed key order. The pending
5
+ // mark (`data-board-pending` on <html>, set before paint by the inline script
6
+ // in PlanInteractions.astro when the URL has a board key) keeps the board
7
+ // hidden until the parsed state has rendered, so a filtered link never shows
8
+ // the unfiltered board first.
9
+ import { useEffect, useState } from 'react';
10
+ import type { Dispatch, SetStateAction } from 'react';
11
+
12
+ import { boardQuery, DEFAULT_STATE, parseBoardQuery } from '../../lib/board';
13
+ import type { BoardState } from '../../lib/board';
14
+
15
+ export function useBoardUrlState(milestoneIds: string[]): [BoardState, Dispatch<SetStateAction<BoardState>>, boolean] {
16
+ const [state, setState] = useState<BoardState>(DEFAULT_STATE);
17
+ // True once the URL's state is applied: the render after it shows the parsed state.
18
+ const [applied, setApplied] = useState(false);
19
+
20
+ useEffect(() => {
21
+ setState(parseBoardQuery(location.search, milestoneIds));
22
+ setApplied(true);
23
+ // Mount only: the milestone list is fixed at build time.
24
+ }, []);
25
+
26
+ useEffect(() => {
27
+ if (!applied) {
28
+ return;
29
+ }
30
+
31
+ // This effect runs after the render that committed the parsed state, so the board is already filtered when it shows.
32
+ delete document.documentElement.dataset.boardPending;
33
+ const url = location.pathname + boardQuery(state) + location.hash;
34
+
35
+ if (url !== location.pathname + location.search + location.hash) {
36
+ history.replaceState(null, '', url);
37
+ }
38
+ }, [state, applied]);
39
+
40
+ return [state, setState, applied];
41
+ }
@@ -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
+ }
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
+ }
@@ -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
+ }