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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/README.md +70 -10
  2. package/dist/cli.js +4 -3
  3. package/dist/dev-env.d.ts +2 -0
  4. package/dist/dev-env.js +13 -0
  5. package/dist/fs-allow.d.ts +2 -0
  6. package/dist/fs-allow.js +11 -0
  7. package/dist/index.js +38 -4
  8. package/dist/options.js +1 -1
  9. package/dist/schema-version.d.ts +17 -0
  10. package/dist/schema-version.js +30 -1
  11. package/dist/sidebar.js +2 -0
  12. package/dist/site-options.js +5 -0
  13. package/dist/types.d.ts +2 -2
  14. package/lib/schema-version.ts +36 -1
  15. package/lib/types.ts +48 -0
  16. package/package.json +7 -3
  17. package/src/components/FeatureSummary.astro +30 -9
  18. package/src/components/FeatureTable.astro +1 -1
  19. package/src/components/ItemDetail.astro +1 -1
  20. package/src/components/ItemDialog.astro +12 -8
  21. package/src/components/RefLink.astro +7 -4
  22. package/src/components/board/Board.tsx +16 -8
  23. package/src/components/board/KanbanItemCard.tsx +4 -2
  24. package/src/components/board/TaskKanbanCard.tsx +4 -2
  25. package/src/components/decisions/Decisions.tsx +162 -0
  26. package/src/components/decisions/useDecisionsUrlState.ts +29 -0
  27. package/src/components/graph/Graph.tsx +290 -0
  28. package/src/components/graph/GraphNodes.tsx +120 -0
  29. package/src/components/graph/useGraphUrlState.ts +58 -0
  30. package/src/components/lib/KanbanItemCard.astro +7 -11
  31. package/src/components/lib/StatusTimelineFeed.astro +3 -2
  32. package/src/components/lib/TaskKanbanCard.astro +2 -1
  33. package/src/components/timeline/Timeline.tsx +39 -6
  34. package/src/components/timeline/useTimelineLayout.ts +2 -2
  35. package/src/content.config.ts +22 -6
  36. package/src/lib/decisions.ts +100 -0
  37. package/src/lib/graph-layout.ts +270 -0
  38. package/src/lib/graph-state.ts +99 -0
  39. package/src/lib/graph.ts +194 -0
  40. package/src/lib/link-html.ts +39 -0
  41. package/src/lib/planning-types.ts +32 -3
  42. package/src/lib/planning.ts +30 -16
  43. package/src/lib/ref-boundary.ts +19 -0
  44. package/src/lib/references.ts +66 -7
  45. package/src/lib/timeline-state.ts +119 -0
  46. package/src/lib/timeline.ts +22 -127
  47. package/src/loaders/adrs.ts +43 -0
  48. package/src/pages/404.astro +18 -0
  49. package/src/pages/index.astro +1 -1
  50. package/src/pages/plan/log.astro +18 -1
  51. package/src/pages/plan/roadmap.astro +1 -1
  52. package/src/routes/plan/decisions/[id].astro +93 -0
  53. package/src/routes/plan/decisions.astro +52 -0
  54. package/src/routes/plan/graph.astro +80 -0
  55. package/src/routes/plan/milestones/index.astro +2 -2
  56. package/src/routes/plan/now.astro +2 -3
  57. package/src/scripts/plan.ts +33 -1
  58. package/src/styles/components.css +117 -3
  59. package/src/styles/graph.css +296 -0
  60. package/src/styles/timeline.css +1 -1
@@ -0,0 +1,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"
@@ -8,13 +8,23 @@
8
8
  // the browser's own scrolling; the wheel listener below only adds Ctrl/Cmd +
9
9
  // wheel zoom and a plain vertical wheel that scrolls a horizontal strip
10
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`.
11
14
  import { useEffect, useLayoutEffect, useRef, useState } from 'react';
12
15
  import type { CSSProperties } from 'react';
13
16
 
14
- import { wheelScrollsStrip, ZOOM, zoomFromWheel, zoomStep } from '../../lib/timeline';
15
- import type { TimelineMilestone } from '../../lib/timeline';
17
+ import { wheelPixels, wheelScrollsStrip, ZOOM, zoomFromWheel, zoomStep } from '../../lib/timeline-state';
18
+ import type { TimelineMilestone } from '../../lib/timeline-state';
16
19
  import { useTimelineLayout } from './useTimelineLayout';
17
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
+
18
28
  function Card({ milestone }: { milestone: TimelineMilestone }) {
19
29
  const { key, id, name, href, isFocus, status, target, progress } = milestone;
20
30
  const title = id === null ? 'No milestone' : `${id} ${name}`;
@@ -111,7 +121,7 @@ export default function Timeline({ milestones }: { milestones: TimelineMilestone
111
121
 
112
122
  if (layout === 'horizontal' && wheelScrollsStrip(event, element)) {
113
123
  event.preventDefault();
114
- element.scrollLeft += event.deltaY;
124
+ element.scrollLeft += wheelPixels(event.deltaY, event.deltaMode, lineHeightOf(element), element.clientWidth);
115
125
  }
116
126
  // Every other wheel passes through, so the page scrolls.
117
127
  };
@@ -134,16 +144,39 @@ export default function Timeline({ milestones }: { milestones: TimelineMilestone
134
144
  </button>
135
145
  </div>
136
146
  <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))}>
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
+ >
138
156
  −
139
157
  </button>
140
158
  <output className="plan-timeline__zoom" aria-live="polite">
141
159
  {Math.round(zoom * 100)}%
142
160
  </output>
143
- <button type="button" aria-label="Zoom in" disabled={zoom >= ZOOM.max} onClick={() => changeZoom(zoomStep(zoom, 1))}>
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
+ >
144
170
  +
145
171
  </button>
146
- <button type="button" disabled={zoom === ZOOM.default} onClick={() => changeZoom(ZOOM.default)}>
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
+ >
147
180
  Reset zoom
148
181
  </button>
149
182
  </div>
@@ -8,8 +8,8 @@
8
8
  // rendered, so a vertical link never flashes horizontal first.
9
9
  import { useEffect, useState } from 'react';
10
10
 
11
- import { parseTimelineQuery, timelineQuery } from '../../lib/timeline';
12
- import type { TimelineLayout } from '../../lib/timeline';
11
+ import { parseTimelineQuery, timelineQuery } from '../../lib/timeline-state';
12
+ import type { TimelineLayout } from '../../lib/timeline-state';
13
13
 
14
14
  export function useTimelineLayout(): [TimelineLayout, (layout: TimelineLayout) => void, boolean] {
15
15
  const [layout, setLayout] = useState<TimelineLayout>('horizontal');
@@ -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
  };
@@ -0,0 +1,100 @@
1
+ // The Decisions view's state: search, status and category filters, grouping,
2
+ // and the query string that keeps them in the URL. Pure, so the island and its
3
+ // tests share it. All from planning.json's `adrs`.
4
+
5
+ import type { Adr, AdrStatus } from './planning-types';
6
+
7
+ /** Every status, in lifecycle order; also the order of status groups. */
8
+ export const ADR_STATUSES: readonly AdrStatus[] = ['proposed', 'accepted', 'deprecated', 'superseded'];
9
+
10
+ export type DecisionsGroup = 'category' | 'status' | 'none';
11
+
12
+ export interface DecisionsState {
13
+ q: string;
14
+ status: AdrStatus[];
15
+ /** Empty means every category. */
16
+ category: string[];
17
+ group: DecisionsGroup;
18
+ }
19
+
20
+ /** Superseded ADRs are hidden until their chip is pressed. */
21
+ export const DEFAULT_DECISIONS_STATE: DecisionsState = { q: '', status: ['proposed', 'accepted', 'deprecated'], category: [], group: 'category' };
22
+
23
+ const GROUPS: readonly DecisionsGroup[] = ['category', 'status', 'none'];
24
+
25
+ const sameList = (a: readonly string[], b: readonly string[]) => a.length === b.length && a.every((value, i) => value === b[i]);
26
+
27
+ /** Parse a query string (with or without `?`); unknown values are dropped and an empty status list falls back to the default. */
28
+ export function parseDecisionsQuery(search: string, categories: string[]): DecisionsState {
29
+ const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
30
+ const listed = (key: string) => (params.get(key) ?? '').split(',').filter((value) => value !== '');
31
+ const status = ADR_STATUSES.filter((value) => listed('status').includes(value));
32
+ const group = params.get('group');
33
+
34
+ return {
35
+ q: params.get('q') ?? '',
36
+ status: status.length ? status : [...DEFAULT_DECISIONS_STATE.status],
37
+ category: [...categories].sort().filter((value) => listed('category').includes(value)),
38
+ group: group !== null && (GROUPS as string[]).includes(group) ? (group as DecisionsGroup) : DEFAULT_DECISIONS_STATE.group,
39
+ };
40
+ }
41
+
42
+ /** The query string for a state, keys in the order q, status, category, group; `''` for the default. */
43
+ export function decisionsQuery(state: DecisionsState): string {
44
+ const pairs: [string, string][] = [];
45
+ const status = ADR_STATUSES.filter((value) => state.status.includes(value));
46
+
47
+ if (state.q !== '') pairs.push(['q', state.q]);
48
+ if (!sameList(status, DEFAULT_DECISIONS_STATE.status)) pairs.push(['status', status.join(',')]);
49
+ if (state.category.length) pairs.push(['category', [...state.category].sort().join(',')]);
50
+ if (state.group !== DEFAULT_DECISIONS_STATE.group) pairs.push(['group', state.group]);
51
+
52
+ return pairs.length ? `?${pairs.map(([key, value]) => `${key}=${encodeURIComponent(value)}`).join('&')}` : '';
53
+ }
54
+
55
+ /** The words a search matches: ID, title, category, and the four sections without Markdown syntax, lower-cased. */
56
+ export function adrSearchText(adr: Adr): string {
57
+ return [adr.id, adr.title, adr.category, adr.context, adr.decision, adr.alternatives, adr.consequences]
58
+ .filter((text): text is string => !!text)
59
+ .join(' ')
60
+ .replace(/[*_`#>|[\]()]/g, ' ')
61
+ .replace(/\s+/g, ' ')
62
+ .trim()
63
+ .toLowerCase();
64
+ }
65
+
66
+ /** Its status and category are selected, and every word of the search appears in its text (adrSearchText, unless given). */
67
+ export function matchesDecision(adr: Pick<Adr, 'status' | 'category'>, state: DecisionsState, text: string = adrSearchText(adr as Adr)): boolean {
68
+ if (adr.status && !state.status.includes(adr.status)) return false;
69
+ if (state.category.length && !state.category.includes(adr.category ?? '')) return false;
70
+
71
+ return state.q
72
+ .toLowerCase()
73
+ .split(/\s+/)
74
+ .filter((word) => word !== '')
75
+ .every((word) => text.includes(word));
76
+ }
77
+
78
+ export interface DecisionGroup<T extends Pick<Adr, 'id' | 'status' | 'category'> = Adr> {
79
+ key: string;
80
+ label: string;
81
+ adrs: T[];
82
+ }
83
+
84
+ const byNumber = <T extends Pick<Adr, 'id'>>(a: T, b: T) => Number(a.id.slice(4)) - Number(b.id.slice(4));
85
+ const capital = (text: string) => text.charAt(0).toUpperCase() + text.slice(1);
86
+
87
+ /** Category groups by name, status groups in lifecycle order, or one group; empty groups are left out, ADRs by ID inside each. */
88
+ export function groupDecisions<T extends Pick<Adr, 'id' | 'status' | 'category'>>(adrs: T[], group: DecisionsGroup): DecisionGroup<T>[] {
89
+ if (group === 'none') return [{ key: 'all', label: 'All decisions', adrs }];
90
+
91
+ const keyOf = (adr: T) => (group === 'status' ? (adr.status ?? 'unknown') : (adr.category ?? 'uncategorised'));
92
+ const keys =
93
+ group === 'status'
94
+ ? [...ADR_STATUSES, 'unknown']
95
+ : [...new Set(adrs.map(keyOf))].sort();
96
+
97
+ return keys
98
+ .map((key) => ({ key, label: capital(key), adrs: adrs.filter((adr) => keyOf(adr) === key).sort(byNumber) }))
99
+ .filter((entry) => entry.adrs.length > 0);
100
+ }