@realadvisor-sites/kit-core 0.4.1 → 0.5.0

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/DESIGN.md CHANGED
@@ -32,7 +32,8 @@ No current website or BRAND.md says "CRM data only": use `agency.logo` and
32
32
 
33
33
  ## 2. Tokens
34
34
 
35
- Put colours, fonts, radii and spacing in `src/styles/tokens.css` and use
35
+ Put colours, fonts, radii and spacing in one tokens file
36
+ (`app/styles/tokens.css` on React Router, `src/styles/tokens.css` on Astro) and use
36
37
  only tokens in components. The kit parts read these (all have fallbacks):
37
38
 
38
39
  ```css
@@ -47,17 +48,39 @@ only tokens in components. The kit parts read these (all have fallbacks):
47
48
  - Text contrast >= 4.5:1 (3:1 for text >= 24px), white text on `--accent`
48
49
  included.
49
50
  - Use `clamp()` for type between phone and desktop.
51
+ - Colour restraint: mostly neutrals, one accent in small doses. A vivid
52
+ brand colour (an electric blue, a signal red) goes in small marks only;
53
+ bands, buttons and large fields take a deep or muted shade of it, the ink
54
+ colour or a neutral surface. TASTE.md is how the result is judged.
50
55
 
51
56
  ## 3. Fonts
52
57
 
53
- Self-hosted only, with `@fontsource/<family>` imported in the layout
54
- frontmatter (the CSP blocks Google Fonts links and font CDNs). At most 2
55
- families and 2 weights per family (a variable font counts as one), latin
56
- subset, `font-display: swap`, and the above-the-fold font preloaded:
58
+ Self-hosted only, with `@fontsource/<family>` imported where the document
59
+ shell is (React Router: `app/root.tsx`; Astro: the layout frontmatter; the
60
+ CSP blocks Google Fonts links and font CDNs). At most 2 families and 2
61
+ weights per family (a variable font counts as one), latin subset,
62
+ `font-display: swap`, and the above-the-fold font preloaded.
63
+
64
+ Choose the pair against the logo, not only from the example: the type
65
+ echoes the logo's character (weight, width, construction, mood) or
66
+ contrasts with it on purpose, and DESIGN-NOTES.md names which (TASTE.md
67
+ line 6). Swapping the example's fonts is expected when the logo is of
68
+ another kind; any open font on @fontsource is allowed.
69
+
70
+ Import and preload:
71
+
72
+ ```tsx
73
+ // app/root.tsx
74
+ import '@fontsource/lato/latin-400.css';
75
+ import lato900 from '@fontsource/lato/files/lato-latin-900-normal.woff2?url';
76
+ <link rel="preload" as="font" type="font/woff2" crossOrigin="" href={lato900} /> {/* in <head> */}
77
+ ```
57
78
 
58
79
  ```astro
80
+ ---
59
81
  import '@fontsource/lato/latin-400.css';
60
82
  import lato900 from '@fontsource/lato/files/lato-latin-900-normal.woff2?url';
83
+ ---
61
84
  <link slot="head" rel="preload" as="font" type="font/woff2" crossorigin href={lato900} />
62
85
  ```
63
86
 
@@ -65,9 +88,12 @@ import lato900 from '@fontsource/lato/files/lato-latin-900-normal.woff2?url';
65
88
 
66
89
  - The `<img data-logo>` sets only its height (or only its width), the
67
90
  other side `auto`: no fixed box, no `object-fit: cover`, no
68
- `aspect-ratio`. At 1440 at least 32px tall and 100px wide (140–180px wide
69
- for a script or detailed logo); at 390 at least 28px tall.
70
- `pnpm screenshot` flags a logo off its file's ratio or below these sizes.
91
+ `aspect-ratio`. Size it by its shape: a wide wordmark at 1440 at least
92
+ 100px wide and 32px tall (140–180px wide for a script or detailed logo),
93
+ at most 72px tall; a tall or square mark (a monogram, 3³) 40–72px tall.
94
+ At 390 at least 28px tall. The header stays slim: at most 12% of the
95
+ screen. `pnpm screenshot` flags a logo off its file's ratio or outside
96
+ these sizes.
71
97
  - Sharp: request 2x the rendered width,
72
98
  `img(agency.logo.url, { w: 360, fit: 'fit', quality: 90 })` for a 180px
73
99
  logo; an SVG in `public/brand/` as is.
@@ -157,7 +183,42 @@ wrap.
157
183
  photo 2"); `alt=""` only for decoration.
158
184
  - No layout shift: every image has `width`/`height` or `aspect-ratio`.
159
185
 
160
- ## 10. Never
186
+ ## 10. Craft defaults
187
+
188
+ Defaults for everything the chosen example does not decide. Where the
189
+ example does something else on purpose, the example wins (TASTE.md judges
190
+ against it); `pnpm screenshot` measures the ones marked (measured).
191
+
192
+ - **Scales, not values.** Spacing, type sizes, radii, borders and shadows
193
+ each come from one scale in the tokens file. No one-off `margin: 37px`.
194
+ A type scale has clear steps: two sizes of one family within 7% of each
195
+ other on the same page read as a mistake.
196
+ - **One grid.** Lay sections out on CSS grid or the `.wrap` container with
197
+ the same gutters; every block starts or ends on an edge another block
198
+ uses. A block aligned to nothing (a link floating in an empty field) is a
199
+ mistake (measured).
200
+ - **Text blocks.** Body text left-aligned with a ragged right edge, never
201
+ justified (measured). Caps only for labels of four words or fewer, never
202
+ for sentences (measured). Emphasis by one means at a time: weight or
203
+ colour or size.
204
+ - **Near-black, not black.** Text and ink in a near-black with a slight
205
+ hue (`#141517`, `#1b1a17`); `#000` only inside the logo or a photo.
206
+ - **Shadows mean raised.** A shadow only on something that floats or
207
+ responds (a menu sheet, a hovered card), one light direction, from the
208
+ shadow scale. Flat surfaces stay flat.
209
+ - **Typographic details** in the page's language:
210
+ - quotation marks „…“ (de), « … » with a thin space (fr), «…» (it, es),
211
+ “…” (en): never straight `"` in text (measured);
212
+ - an en dash for ranges (2–4 Zimmer, 9–18 Uhr), with no spaces;
213
+ - a non-breaking space between a number and its unit or currency
214
+ (`CHF 1'100'000`, `257 m²`, `4.5 Zimmer`): the kit's `formatPrice()`
215
+ and `formatSurface()` already do it;
216
+ - tabular figures (`font-variant-numeric: tabular-nums`) for prices and
217
+ counts in lists, so columns of numbers line up.
218
+ - **States.** Empty, loading and error states are designed like the rest
219
+ (AGENTS.md section 3): a sentence and a way on, never a blank box.
220
+
221
+ ## 11. Never
161
222
 
162
223
  - Invented content: lorem ipsum, testimonials, awards, statistics, agents,
163
224
  stock handshakes. No data, no section.
package/README.md CHANGED
@@ -6,9 +6,9 @@ The framework-neutral core of a RealAdvisor site, shared by the Astro kit
6
6
  version, and never copies it:
7
7
 
8
8
  ```json
9
- "@realadvisor/sites-kit-core": "npm:@realadvisor-sites/kit-core@^0.4.0",
10
- "@realadvisor/sites-kit-astro": "npm:@realadvisor-sites/kit-astro@^0.4.0",
11
- "@realadvisor/sites-sdk": "npm:@realadvisor-sites/sdk@^0.4.0"
9
+ "@realadvisor/sites-kit-core": "npm:@realadvisor-sites/kit-core@^0.5.0",
10
+ "@realadvisor/sites-kit-astro": "npm:@realadvisor-sites/kit-astro@^0.5.0",
11
+ "@realadvisor/sites-sdk": "npm:@realadvisor-sites/sdk@^0.5.0"
12
12
  ```
13
13
 
14
14
  In this repo the template and examples use paths instead (`file:../kit-core`).
package/bin/sites-kit.mjs CHANGED
@@ -4,8 +4,10 @@
4
4
  * site's package scripts). Every tool lives in the package, never in the
5
5
  * site: a site always runs the kit's current version.
6
6
  *
7
- * sites-kit fixture [name | file.json] [--if-empty] sample data into src/data/
7
+ * sites-kit fixture [name | file.json] [--if-empty] sample data into src/data/ (React: app/data/fixture.json)
8
8
  * sites-kit screenshot [paths...] [options] screenshots (your eyes)
9
+ * sites-kit critic [path] [--anchor url | --anchor-shots a.png,b.png] inputs for the taste critic (TASTE.md)
10
+ * sites-kit critic calibrate prepare --url <example> | score does the critic still catch known faults
9
11
  * sites-kit check deploy [--no-build] the deploy gate (pnpm check:deploy)
10
12
  * sites-kit test map [--url ...] [--path ...] browser test of the listings map
11
13
  */
@@ -15,6 +17,8 @@ import { fileURLToPath } from 'node:url';
15
17
  const TOOLS = {
16
18
  fixture: 'use-fixture.mjs',
17
19
  screenshot: 'screenshot.mjs',
20
+ critic: 'critic.mjs',
21
+ 'critic calibrate': 'critic-calibrate.mjs',
18
22
  'check deploy': 'check-deploy.mjs',
19
23
  'test map': 'search-map-test.mjs',
20
24
  };
@@ -21,6 +21,12 @@ const TEXT = {
21
21
  en: ['Page temporarily unavailable', 'Please try again in a few minutes.', 'Back to home'],
22
22
  } as const;
23
23
 
24
+ /** Title, text and home-link label of the 500 page in a language (a framework's own error page uses them too). */
25
+ export const serverErrorText = (l: keyof typeof TEXT = lang()) => {
26
+ const [title, body, home] = TEXT[l];
27
+ return { title, body, home };
28
+ };
29
+
24
30
  export function renderFailed(path: string, err: unknown): Response {
25
31
  const e = err instanceof Error ? err : new Error(String(err));
26
32
  const msg = err instanceof SitesApiError && err.code === 'site_key' ? `page render failed: ${SITE_KEY_REJECTED}` : 'page render failed';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@realadvisor-sites/kit-core",
3
- "version": "0.4.1",
3
+ "version": "0.5.0",
4
4
  "description": "The framework-neutral core of a RealAdvisor site, shared by the Astro kit and the React kit: data helpers over @realadvisor/sites-sdk (a peer), i18n, formatting, legal texts, SEO, search, images, security headers, the browser scripts (listing search and map, enquiry, consent), the sites-kit tools (fixture, screenshot, deploy check) and the rules the coding agent follows (AGENTS.md, DESIGN.md).",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -19,6 +19,7 @@
19
19
  "*.mjs",
20
20
  "*.mts",
21
21
  "AGENTS.md",
22
+ "CHANGELOG.md",
22
23
  "DESIGN.md",
23
24
  "README.md",
24
25
  "LICENSE",
@@ -54,7 +55,7 @@
54
55
  "test": "node --experimental-strip-types --no-warnings=ExperimentalWarning --test \"test/*.test.mjs\" \"test/*.test.ts\""
55
56
  },
56
57
  "peerDependencies": {
57
- "@realadvisor/sites-sdk": "^0.4.1",
58
+ "@realadvisor/sites-sdk": "^0.5.0",
58
59
  "playwright": "^1.64.1"
59
60
  },
60
61
  "peerDependenciesMeta": {
@@ -0,0 +1,95 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Calibrate the taste critic (TASTE.md section 5): does it still catch every
4
+ * fault a user once had to point out, and leave the clean example alone?
5
+ *
6
+ * sites-kit critic calibrate prepare --url http://localhost:4511 [--out critic-calibration]
7
+ * one critic-input/ folder per case in critic/calibration/cases.json,
8
+ * for the example running at --url (the anchor is the same page, clean)
9
+ * (the run harness gives each <out>/<case>/INDEX.md to the critic and saves
10
+ * its answer as <out>/<case>/answer.md)
11
+ * sites-kit critic calibrate score [--out critic-calibration]
12
+ * compares every answer.md with the case's expected scores; exit 1 on a miss
13
+ */
14
+ import { spawnSync } from 'node:child_process';
15
+ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
16
+ import { join, resolve } from 'node:path';
17
+ import { fileURLToPath } from 'node:url';
18
+
19
+ /** Scores from a critic answer: { lines: { 1: 2, ... }, total }. */
20
+ export function parseScores(md) {
21
+ const lines = {};
22
+ const section = md.split(/^## Scores\s*$/m)[1]?.split(/^## /m)[0] ?? md;
23
+ for (const m of section.matchAll(/^\s*(\d{1,2})\.\s+[^\n]*?\s([012])\s*:/gm)) lines[Number(m[1])] = Number(m[2]);
24
+ const t = md.match(/Total:\s*(\d+)\s*\/\s*(\d+)/);
25
+ const sum = Object.values(lines).reduce((a, b) => a + b, 0);
26
+ return { lines, total: t ? Number(t[1]) : sum, outOf: t ? Number(t[2]) : null };
27
+ }
28
+
29
+ /** Problems of one case's scores against its expectations ([] = pass). */
30
+ export function checkCase(scores, expect) {
31
+ const out = [];
32
+ const test = (name, v, e) => {
33
+ if (v === undefined) return out.push(`line ${name}: no score found`);
34
+ if (e.min !== undefined && v < e.min) out.push(`line ${name}: ${v}, expected at least ${e.min}`);
35
+ if (e.max !== undefined && v > e.max) out.push(`line ${name}: ${v}, expected at most ${e.max}`);
36
+ };
37
+ for (const [k, e] of Object.entries(expect)) {
38
+ if (k === 'total') {
39
+ if (e.min !== undefined && scores.total < e.min) out.push(`total ${scores.total}, expected at least ${e.min}`);
40
+ if (e.max !== undefined && scores.total > e.max) out.push(`total ${scores.total}, expected at most ${e.max}`);
41
+ } else if (k === 'all') {
42
+ for (const [n, v] of Object.entries(scores.lines)) test(n, v, e);
43
+ } else test(k, scores.lines[Number(k)], e);
44
+ }
45
+ return out;
46
+ }
47
+
48
+ const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
49
+ if (isMain) {
50
+ const args = process.argv.slice(2).filter((a) => a !== '--');
51
+ const opt = (name, def) => {
52
+ const i = args.indexOf(`--${name}`);
53
+ return i === -1 ? def : args.splice(i, 2)[1];
54
+ };
55
+ const OUT = resolve(opt('out', 'critic-calibration'));
56
+ const URL_ = opt('url', '');
57
+ const dir = fileURLToPath(new URL('../critic/calibration/', import.meta.url));
58
+ const { cases } = JSON.parse(readFileSync(join(dir, 'cases.json'), 'utf8'));
59
+ const cmd = args[0];
60
+ if (cmd === 'prepare') {
61
+ if (!URL_) {
62
+ console.error('--url: the example of the cases running (e.g. studio-vey: pnpm --dir examples/react/studio-vey dev)');
63
+ process.exit(2);
64
+ }
65
+ for (const c of cases) {
66
+ const out = join(OUT, c.id);
67
+ const inject = c.inject ? ['--inject', join(dir, c.inject)] : [];
68
+ const run = spawnSync(process.execPath, [fileURLToPath(new URL('./critic.mjs', import.meta.url)), c.path, '--url', URL_, '--anchor', URL_, '--anchor-path', c.path, '--out', out, ...inject], { stdio: 'inherit' });
69
+ if (run.status) process.exit(run.status);
70
+ }
71
+ console.log(`\n${cases.length} cases in ${OUT}/. Give each <case>/INDEX.md to the critic (a separate model, nothing else), save its answer as <case>/answer.md, then run: sites-kit critic calibrate score`);
72
+ } else if (cmd === 'score') {
73
+ let misses = 0;
74
+ const report = [];
75
+ for (const c of cases) {
76
+ const f = join(OUT, c.id, 'answer.md');
77
+ if (!existsSync(f)) {
78
+ misses++;
79
+ console.log(`✗ ${c.id}: no answer.md`);
80
+ continue;
81
+ }
82
+ const scores = parseScores(readFileSync(f, 'utf8'));
83
+ const problems = checkCase(scores, c.expect);
84
+ if (problems.length) misses++;
85
+ report.push({ id: c.id, fault: c.fault, scores, problems });
86
+ console.log(`${problems.length ? '✗' : '✓'} ${c.id} (${c.fault}): total ${scores.total}${scores.outOf ? `/${scores.outOf}` : ''}${problems.map((p) => `\n ${p}`).join('')}`);
87
+ }
88
+ writeFileSync(join(OUT, 'score.json'), JSON.stringify(report, null, 2));
89
+ console.log(`\n${cases.length - misses}/${cases.length} cases pass.`);
90
+ process.exit(misses ? 1 : 0);
91
+ } else {
92
+ console.error('Usage: sites-kit critic calibrate prepare --url <example url> | score [--out dir]');
93
+ process.exit(2);
94
+ }
95
+ }