@blueprint-chart/docs 0.1.19 → 0.1.20
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/dist/api.d.ts +13 -0
- package/dist/api.js +29 -0
- package/dist/manifest.json +242 -0
- package/package.json +5 -4
package/dist/api.d.ts
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
export type DocGroup = 'handbook' | 'guide' | 'charts' | 'reference/dsl' | 'reference/api';
|
|
2
|
+
export interface DocEntry {
|
|
3
|
+
slug: string;
|
|
4
|
+
group: DocGroup;
|
|
5
|
+
title: string;
|
|
6
|
+
blurb: string;
|
|
7
|
+
mdPath: string;
|
|
8
|
+
}
|
|
9
|
+
export declare function listDocs(group?: DocGroup): DocEntry[];
|
|
10
|
+
export declare function getDoc(group: DocGroup, slug: string): {
|
|
11
|
+
entry: DocEntry;
|
|
12
|
+
content: string;
|
|
13
|
+
};
|
package/dist/api.js
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { readFileSync, existsSync } from 'node:fs';
|
|
2
|
+
import { join, dirname } from 'node:path';
|
|
3
|
+
import { fileURLToPath } from 'node:url';
|
|
4
|
+
const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
|
|
5
|
+
let cached;
|
|
6
|
+
function loadManifest() {
|
|
7
|
+
if (cached) {
|
|
8
|
+
return cached;
|
|
9
|
+
}
|
|
10
|
+
const manifestPath = join(PKG_ROOT, 'dist', 'manifest.json');
|
|
11
|
+
if (!existsSync(manifestPath)) {
|
|
12
|
+
throw new Error(`@blueprint-chart/docs: manifest.json not found at ${manifestPath}. `
|
|
13
|
+
+ `Did you run \`pnpm --filter @blueprint-chart/docs build\`?`);
|
|
14
|
+
}
|
|
15
|
+
cached = JSON.parse(readFileSync(manifestPath, 'utf8'));
|
|
16
|
+
return cached;
|
|
17
|
+
}
|
|
18
|
+
export function listDocs(group) {
|
|
19
|
+
const all = loadManifest().entries;
|
|
20
|
+
return group ? all.filter(e => e.group === group) : all;
|
|
21
|
+
}
|
|
22
|
+
export function getDoc(group, slug) {
|
|
23
|
+
const entry = loadManifest().entries.find(e => e.group === group && e.slug === slug);
|
|
24
|
+
if (!entry) {
|
|
25
|
+
throw new Error(`@blueprint-chart/docs: no doc at ${group}/${slug}`);
|
|
26
|
+
}
|
|
27
|
+
const content = readFileSync(join(PKG_ROOT, 'src', entry.mdPath), 'utf8');
|
|
28
|
+
return { entry, content };
|
|
29
|
+
}
|
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
{
|
|
2
|
+
"entries": [
|
|
3
|
+
{
|
|
4
|
+
"slug": "accessibility",
|
|
5
|
+
"group": "handbook",
|
|
6
|
+
"title": "Accessibility",
|
|
7
|
+
"blurb": "> Accessible charts are honest charts. CVD simulation, sufficient contrast, meaningful alt text, keyboard and screen-reader support, legible typography, and — above all — never encoding information in",
|
|
8
|
+
"mdPath": "handbook/accessibility.md"
|
|
9
|
+
},
|
|
10
|
+
{
|
|
11
|
+
"slug": "annotations",
|
|
12
|
+
"group": "handbook",
|
|
13
|
+
"title": "Annotations",
|
|
14
|
+
"blurb": "> Annotations guide the reader to the story in the data. They explain design elements, highlight significant values, and provide context the chart alone cannot convey. Used well, they do most of the s",
|
|
15
|
+
"mdPath": "handbook/annotations.md"
|
|
16
|
+
},
|
|
17
|
+
{
|
|
18
|
+
"slug": "anti-patterns",
|
|
19
|
+
"group": "handbook",
|
|
20
|
+
"title": "Anti-Patterns",
|
|
21
|
+
"blurb": "> A catalog of what goes wrong: misleading practices that distort the truth, design anti-patterns that obscure the story, and the statistical integrity rules that keep charts honest.",
|
|
22
|
+
"mdPath": "handbook/anti-patterns.md"
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
"slug": "axes",
|
|
26
|
+
"group": "handbook",
|
|
27
|
+
"title": "Axes & Grid Lines",
|
|
28
|
+
"blurb": "> When zero matters, when it doesn't, how grid lines should whisper rather than shout, how to format numbers, when to use logarithmic scales, and how aspect ratio silently changes a chart's story.",
|
|
29
|
+
"mdPath": "handbook/axes.md"
|
|
30
|
+
},
|
|
31
|
+
{
|
|
32
|
+
"slug": "choosing",
|
|
33
|
+
"group": "handbook",
|
|
34
|
+
"title": "Choosing the Right Chart",
|
|
35
|
+
"blurb": "> Before picking a visualization type, answer three questions about goal, content, and audience. Then pick the simplest chart that answers the question. Increase complexity only when the simpler form ",
|
|
36
|
+
"mdPath": "handbook/choosing.md"
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
"slug": "color",
|
|
40
|
+
"group": "handbook",
|
|
41
|
+
"title": "Color & Palettes",
|
|
42
|
+
"blurb": "> Palette types, seven key rules, the perceptual-uniformity trap (HCL vs. HSL), ten techniques for reducing color usage, dark mode adjustments, and the components of an organizational palette system.",
|
|
43
|
+
"mdPath": "handbook/color.md"
|
|
44
|
+
},
|
|
45
|
+
{
|
|
46
|
+
"slug": "design-principles",
|
|
47
|
+
"group": "handbook",
|
|
48
|
+
"title": "Design Principles",
|
|
49
|
+
"blurb": "> The core principles behind every good chart: purposefulness, clarity, data-ink ratio, restraint, consistency, starting with grey, the power of comparisons, and the refusal to use 3D.",
|
|
50
|
+
"mdPath": "handbook/design-principles.md"
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
"slug": "frame-elements",
|
|
54
|
+
"group": "handbook",
|
|
55
|
+
"title": "Frame Elements",
|
|
56
|
+
"blurb": "> A well-structured chart frame has a clear information hierarchy: title, description, chart area, annotations, axis labels, note, source, and credit. Each element has a role and a style treatment tha",
|
|
57
|
+
"mdPath": "handbook/frame-elements.md"
|
|
58
|
+
},
|
|
59
|
+
{
|
|
60
|
+
"slug": "labels",
|
|
61
|
+
"group": "handbook",
|
|
62
|
+
"title": "Labels & Legends",
|
|
63
|
+
"blurb": "> Direct labeling beats legends wherever possible. When you must use a legend, place it where it helps. Use value labels when precision matters and the layout allows.",
|
|
64
|
+
"mdPath": "handbook/labels.md"
|
|
65
|
+
},
|
|
66
|
+
{
|
|
67
|
+
"slug": "tooltips",
|
|
68
|
+
"group": "handbook",
|
|
69
|
+
"title": "Tooltips & Interaction",
|
|
70
|
+
"blurb": "> Tooltips progressively disclose detail, they never replace critical information. Interaction must be consistent, accessible, and keyboard-reachable. Crosshairs and hover states support — not replace",
|
|
71
|
+
"mdPath": "handbook/tooltips.md"
|
|
72
|
+
},
|
|
73
|
+
{
|
|
74
|
+
"slug": "typography",
|
|
75
|
+
"group": "handbook",
|
|
76
|
+
"title": "Typography",
|
|
77
|
+
"blurb": "> Type in charts must be small, sharp, and legible at a glance. Use sans-serifs with unambiguous character shapes, size ruthlessly, never rotate, prefer sentence case, and left-align.",
|
|
78
|
+
"mdPath": "handbook/typography.md"
|
|
79
|
+
},
|
|
80
|
+
{
|
|
81
|
+
"slug": "accessibility",
|
|
82
|
+
"group": "guide",
|
|
83
|
+
"title": "Accessibility",
|
|
84
|
+
"blurb": "> WCAG contrast checks, colour-vision-deficiency simulation, and palette-safety audits — built into the library.",
|
|
85
|
+
"mdPath": "guide/accessibility.md"
|
|
86
|
+
},
|
|
87
|
+
{
|
|
88
|
+
"slug": "data-transforms",
|
|
89
|
+
"group": "guide",
|
|
90
|
+
"title": "Data Transforms",
|
|
91
|
+
"blurb": "> A composable pipeline that shapes raw tabular data into the rows the chart actually renders.",
|
|
92
|
+
"mdPath": "guide/data-transforms.md"
|
|
93
|
+
},
|
|
94
|
+
{
|
|
95
|
+
"slug": "dsl-editor",
|
|
96
|
+
"group": "guide",
|
|
97
|
+
"title": "DSL Editor",
|
|
98
|
+
"blurb": "> The BPC source editor — CodeMirror 6, a Lezer-generated grammar, syntax highlighting tuned for prose-shaped charts, and two-way sync with the visual panels.",
|
|
99
|
+
"mdPath": "guide/dsl-editor.md"
|
|
100
|
+
},
|
|
101
|
+
{
|
|
102
|
+
"slug": "embed",
|
|
103
|
+
"group": "guide",
|
|
104
|
+
"title": "embed",
|
|
105
|
+
"blurb": "Blueprint Chart is **static-first**: every chart is a self-contained artifact independent of any vendor server. There are three ways to put one on a page, and they all run entirely in the browser.",
|
|
106
|
+
"mdPath": "guide/embed.md"
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
"slug": "getting-started",
|
|
110
|
+
"group": "guide",
|
|
111
|
+
"title": "getting started",
|
|
112
|
+
"blurb": "Blueprint Chart is published as four packages on NPM. Pick the one that matches what you're building.",
|
|
113
|
+
"mdPath": "guide/getting-started.md"
|
|
114
|
+
},
|
|
115
|
+
{
|
|
116
|
+
"slug": "palettes",
|
|
117
|
+
"group": "guide",
|
|
118
|
+
"title": "Palettes",
|
|
119
|
+
"blurb": "> 50+ curated categorical palettes, plus the helpers to resolve, audit, and adjust them for the background you render against.",
|
|
120
|
+
"mdPath": "guide/palettes.md"
|
|
121
|
+
},
|
|
122
|
+
{
|
|
123
|
+
"slug": "scenes",
|
|
124
|
+
"group": "guide",
|
|
125
|
+
"title": "Scenes",
|
|
126
|
+
"blurb": "> Same chart, different states — composed into a story that a reader can step through.",
|
|
127
|
+
"mdPath": "guide/scenes.md"
|
|
128
|
+
},
|
|
129
|
+
{
|
|
130
|
+
"slug": "area-stacked",
|
|
131
|
+
"group": "charts",
|
|
132
|
+
"title": "Stacked area chart",
|
|
133
|
+
"blurb": "> Multi-series stacked area chart for composition over time; supports percent stacking.",
|
|
134
|
+
"mdPath": "charts/area-stacked.md"
|
|
135
|
+
},
|
|
136
|
+
{
|
|
137
|
+
"slug": "area",
|
|
138
|
+
"group": "charts",
|
|
139
|
+
"title": "Area chart",
|
|
140
|
+
"blurb": "> Single-series area chart for magnitude over time; pairs with `areaFill`.",
|
|
141
|
+
"mdPath": "charts/area.md"
|
|
142
|
+
},
|
|
143
|
+
{
|
|
144
|
+
"slug": "bar-grouped",
|
|
145
|
+
"group": "charts",
|
|
146
|
+
"title": "Grouped bar chart",
|
|
147
|
+
"blurb": "> Multi-series grouped vertical bar chart for grouped categorical comparison across a second dimension.",
|
|
148
|
+
"mdPath": "charts/bar-grouped.md"
|
|
149
|
+
},
|
|
150
|
+
{
|
|
151
|
+
"slug": "bar-horizontal",
|
|
152
|
+
"group": "charts",
|
|
153
|
+
"title": "Horizontal bar chart",
|
|
154
|
+
"blurb": "> Single-series horizontal bar chart for long category labels and ranked bars.",
|
|
155
|
+
"mdPath": "charts/bar-horizontal.md"
|
|
156
|
+
},
|
|
157
|
+
{
|
|
158
|
+
"slug": "bar-multi",
|
|
159
|
+
"group": "charts",
|
|
160
|
+
"title": "Multi-series bar chart",
|
|
161
|
+
"blurb": "> Multi-series vertical bar chart for side-by-side comparison of a small group of series.",
|
|
162
|
+
"mdPath": "charts/bar-multi.md"
|
|
163
|
+
},
|
|
164
|
+
{
|
|
165
|
+
"slug": "bar-split",
|
|
166
|
+
"group": "charts",
|
|
167
|
+
"title": "Split bar chart",
|
|
168
|
+
"blurb": "> Diverging vertical bar chart for values around a shared baseline (positive/negative).",
|
|
169
|
+
"mdPath": "charts/bar-split.md"
|
|
170
|
+
},
|
|
171
|
+
{
|
|
172
|
+
"slug": "bar-stacked",
|
|
173
|
+
"group": "charts",
|
|
174
|
+
"title": "Stacked bar chart",
|
|
175
|
+
"blurb": "> Stacked horizontal bar chart for composition within a category, emphasising the total.",
|
|
176
|
+
"mdPath": "charts/bar-stacked.md"
|
|
177
|
+
},
|
|
178
|
+
{
|
|
179
|
+
"slug": "bar-vertical",
|
|
180
|
+
"group": "charts",
|
|
181
|
+
"title": "Vertical bar chart",
|
|
182
|
+
"blurb": "> Single-series vertical bar chart for ranked categorical comparison, small N.",
|
|
183
|
+
"mdPath": "charts/bar-vertical.md"
|
|
184
|
+
},
|
|
185
|
+
{
|
|
186
|
+
"slug": "column-stacked",
|
|
187
|
+
"group": "charts",
|
|
188
|
+
"title": "Stacked column chart",
|
|
189
|
+
"blurb": "> Stacked vertical column chart for composition over discrete columns; supports percent stacking.",
|
|
190
|
+
"mdPath": "charts/column-stacked.md"
|
|
191
|
+
},
|
|
192
|
+
{
|
|
193
|
+
"slug": "donut",
|
|
194
|
+
"group": "charts",
|
|
195
|
+
"title": "Donut chart",
|
|
196
|
+
"blurb": "> Circular part-to-whole chart with a central label slot.",
|
|
197
|
+
"mdPath": "charts/donut.md"
|
|
198
|
+
},
|
|
199
|
+
{
|
|
200
|
+
"slug": "line-multi",
|
|
201
|
+
"group": "charts",
|
|
202
|
+
"title": "Multi-line chart",
|
|
203
|
+
"blurb": "> Multi-series line chart for comparing several time series or trends.",
|
|
204
|
+
"mdPath": "charts/line-multi.md"
|
|
205
|
+
},
|
|
206
|
+
{
|
|
207
|
+
"slug": "line",
|
|
208
|
+
"group": "charts",
|
|
209
|
+
"title": "Line chart",
|
|
210
|
+
"blurb": "> Single-series line chart for continuous trend over an ordered domain.",
|
|
211
|
+
"mdPath": "charts/line.md"
|
|
212
|
+
},
|
|
213
|
+
{
|
|
214
|
+
"slug": "pie",
|
|
215
|
+
"group": "charts",
|
|
216
|
+
"title": "Pie chart",
|
|
217
|
+
"blurb": "> Circular part-to-whole chart for very small N.",
|
|
218
|
+
"mdPath": "charts/pie.md"
|
|
219
|
+
},
|
|
220
|
+
{
|
|
221
|
+
"slug": "annotations",
|
|
222
|
+
"group": "reference/dsl",
|
|
223
|
+
"title": "annotations",
|
|
224
|
+
"blurb": "Two families of named blocks that target specific data values to draw the eye: **color directives** (`colorize`, `highlight`, `areafill`) recolor or emphasize parts of the chart, and **annotations** (",
|
|
225
|
+
"mdPath": "reference/dsl/annotations.md"
|
|
226
|
+
},
|
|
227
|
+
{
|
|
228
|
+
"slug": "properties",
|
|
229
|
+
"group": "reference/dsl",
|
|
230
|
+
"title": "properties",
|
|
231
|
+
"blurb": "Value-bearing constructs in a `.bpc` document: key/value properties on the chart, the `data` block carrying values, and `series` overrides for per-series visual control. See [DSL overview](/reference/",
|
|
232
|
+
"mdPath": "reference/dsl/properties.md"
|
|
233
|
+
},
|
|
234
|
+
{
|
|
235
|
+
"slug": "scenes-and-transforms",
|
|
236
|
+
"group": "reference/dsl",
|
|
237
|
+
"title": "scenes and transforms",
|
|
238
|
+
"blurb": "Story-level constructs: **scenes** compose multiple visualisation states into a stepable narrative, and **transforms** describe data-pipeline operations applied before rendering. Scenes can override a",
|
|
239
|
+
"mdPath": "reference/dsl/scenes-and-transforms.md"
|
|
240
|
+
}
|
|
241
|
+
]
|
|
242
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@blueprint-chart/docs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.20",
|
|
4
4
|
"description": "Public documentation for Blueprint Chart — handbook, guide, BPC DSL spec, and lib API reference.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -48,15 +48,16 @@
|
|
|
48
48
|
"vitepress": "^1.5.0",
|
|
49
49
|
"vitest": "^3.2.4",
|
|
50
50
|
"vue": "^3.5",
|
|
51
|
-
"@blueprint-chart/
|
|
52
|
-
"@blueprint-chart/
|
|
51
|
+
"@blueprint-chart/lib": "0.1.20",
|
|
52
|
+
"@blueprint-chart/ui": "0.1.20"
|
|
53
53
|
},
|
|
54
54
|
"scripts": {
|
|
55
55
|
"dev": "vitepress dev src --host 0.0.0.0 --port 4445",
|
|
56
56
|
"build:vitepress": "vitepress build src",
|
|
57
57
|
"build:manifest": "tsx scripts/build-manifest.ts",
|
|
58
58
|
"build:api": "tsc --project tsconfig.api.json",
|
|
59
|
-
"build": "pnpm run build:
|
|
59
|
+
"build:package": "pnpm run build:manifest && pnpm run build:api",
|
|
60
|
+
"build": "pnpm run build:vitepress && pnpm run build:package",
|
|
60
61
|
"preview": "vitepress preview src --host 0.0.0.0 --port 4445",
|
|
61
62
|
"test": "vitest run"
|
|
62
63
|
}
|