domma-cms 1.67.2 → 1.68.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.
Files changed (79) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/CLAUDE.md +2 -0
  3. package/admin/js/lib/layouts-arrange.js +1 -1
  4. package/admin/js/lib/rich-field.js +9 -2
  5. package/admin/js/lib/seo-defaults.js +1 -1
  6. package/admin/js/templates/docs/api-content.html +3 -2
  7. package/admin/js/templates/docs/api-layouts.html +1 -1
  8. package/admin/js/templates/docs/usage-navigation.html +2 -1
  9. package/admin/js/templates/docs/usage-pages.html +3 -1
  10. package/admin/js/templates/docs/usage-search-engines.html +3 -0
  11. package/admin/js/templates/page-editor.html +3 -3
  12. package/admin/js/views/form-editor.js +5 -5
  13. package/admin/js/views/layouts.js +7 -7
  14. package/admin/js/views/menu-editor.js +20 -20
  15. package/admin/js/views/page-editor.js +9 -9
  16. package/admin/js/views/seo.js +31 -30
  17. package/docs/DommaFeatures.md +6 -2
  18. package/docs/api-reference.md +7 -3
  19. package/docs/guides/multi-page-forms.md +1 -1
  20. package/docs/plugin-development.md +20 -0
  21. package/package.json +1 -1
  22. package/plugins/blog/CHANGELOG.md +3 -0
  23. package/plugins/blog/CLAUDE.md +15 -0
  24. package/plugins/blog/admin/views/categories.js +5 -2
  25. package/plugins/blog/admin/views/kit.js +19 -0
  26. package/plugins/blog/docs/guide.md +2 -0
  27. package/plugins/blog/plugin.js +18 -2
  28. package/plugins/blog/plugin.json +6 -6
  29. package/plugins/blog/plugin.public.js +16 -2
  30. package/plugins/blog/public/blog.css +3 -0
  31. package/plugins/blog/tests/public.test.js +29 -2
  32. package/plugins/feedback/CLAUDE.md +22 -0
  33. package/plugins/feedback/admin/css/index.css +2 -0
  34. package/plugins/feedback/admin/views/inbox.js +5 -2
  35. package/plugins/feedback/admin/views/send.js +12 -5
  36. package/plugins/feedback/docs/guide.md +3 -2
  37. package/plugins/feedback/lib/sender.js +1 -1
  38. package/plugins/feedback/lib/shape.js +72 -11
  39. package/plugins/feedback/plugin.js +3 -3
  40. package/plugins/feedback/plugin.json +3 -2
  41. package/plugins/feedback/tests/api.test.js +47 -1
  42. package/plugins/feedback/tests/shape.test.js +87 -1
  43. package/plugins/free-tier.lock.json +43 -42
  44. package/plugins/shopping-cart/CHANGELOG.md +20 -0
  45. package/plugins/shopping-cart/CLAUDE.md +38 -1
  46. package/plugins/shopping-cart/admin/css/index.css +4 -0
  47. package/plugins/shopping-cart/admin/lib/kit.js +1 -0
  48. package/plugins/shopping-cart/admin/views/products.js +95 -3
  49. package/plugins/shopping-cart/admin/views/shop.js +2 -1
  50. package/plugins/shopping-cart/docs/guide.md +6 -1
  51. package/plugins/shopping-cart/inject/body.html +2 -2
  52. package/plugins/shopping-cart/lib/description.js +173 -0
  53. package/plugins/shopping-cart/lib/render.js +3 -2
  54. package/plugins/shopping-cart/lib/shop.js +4 -1
  55. package/plugins/shopping-cart/plugin.js +17 -2
  56. package/plugins/shopping-cart/plugin.json +3 -2
  57. package/plugins/shopping-cart/plugin.public.js +6 -9
  58. package/plugins/shopping-cart/public/lib/products.js +40 -3
  59. package/plugins/shopping-cart/public/shop.css +1 -0
  60. package/plugins/shopping-cart/tests/pure.test.js +26 -1
  61. package/plugins/shopping-cart/tests/seo.test.js +174 -0
  62. package/public/js/menu-cards.mjs +4 -4
  63. package/public/js/menu-look.mjs +1 -1
  64. package/public/js/rich-text.mjs +4 -4
  65. package/public/js/site.js +1 -1
  66. package/server/routes/api/forms.js +5 -3
  67. package/server/routes/api/layouts.js +8 -4
  68. package/server/routes/api/seo.js +10 -4
  69. package/server/services/content.js +23 -0
  70. package/server/services/contentApi.js +27 -4
  71. package/server/services/forms.js +58 -2
  72. package/server/services/health.js +3 -1
  73. package/server/services/markdown.js +2 -2
  74. package/server/services/menus.js +56 -6
  75. package/server/services/renderer.js +28 -4
  76. package/server/services/richText.js +56 -3
  77. package/server/services/search.js +5 -2
  78. package/server/services/sitemap.js +5 -3
  79. package/server/templates/page.html +1 -1
@@ -12,6 +12,7 @@ import {getConfig, saveConfig} from '../config.js';
12
12
  import {CONTENT_RESOURCES} from './apiTokens.js';
13
13
  import {isPubliclyListed} from './search.js';
14
14
  import {plural} from './sidebarBadges.js';
15
+ import {isRichText, renderRichText, richTextLine} from './richText.js';
15
16
 
16
17
  export const FORMATS = Object.freeze(['html', 'markdown']);
17
18
 
@@ -131,9 +132,27 @@ export function domma(html) {
131
132
  * @returns {object}
132
133
  */
133
134
  export function pageSummary(page) {
134
- return pick(page, SUMMARY_KEYS);
135
+ return withDescription(pick(page, SUMMARY_KEYS));
135
136
  }
136
137
 
138
+ /**
139
+ * A page's `description` as API consumers have always had it - plain text -
140
+ * with `descriptionHtml` beside it: the same words as safe HTML (formatted
141
+ * when the description was written in the rich editor, escaped paragraphs
142
+ * when it is plain). Neither key is added to a page without a description.
143
+ *
144
+ * @param {object} out - a payload holding `description` as stored
145
+ * @returns {object}
146
+ */
147
+ function withDescription(out) {
148
+ if (typeof out.description !== 'string') return out;
149
+ const html = renderRichText(out.description);
150
+ return {...out, description: richTextLine(out.description), ...(html && {descriptionHtml: html})};
151
+ }
152
+
153
+ /** An SEO block's description as the meta tag carries it: plain text. */
154
+ const plainSeo = (seo) => (isRichText(seo.description) ? {...seo, description: richTextLine(seo.description)} : seo);
155
+
137
156
  /**
138
157
  * One page. `html` is the body only (page.html), not the full document with
139
158
  * navbar and footer; `markdown` is the source, shortcodes and all.
@@ -143,8 +162,8 @@ export function pageSummary(page) {
143
162
  * @returns {object}
144
163
  */
145
164
  export function pageDetail(page, {format}) {
146
- const out = pick(page, DETAIL_KEYS);
147
- if (page.seo && typeof page.seo === 'object') out.seo = pick(page.seo, SEO_KEYS);
165
+ const out = withDescription(pick(page, DETAIL_KEYS));
166
+ if (page.seo && typeof page.seo === 'object') out.seo = plainSeo(pick(page.seo, SEO_KEYS));
148
167
  if (format === 'html' || format === 'both') out.html = page.html || '';
149
168
  if (format === 'markdown' || format === 'both') out.markdown = page.content || '';
150
169
  const custom = Array.isArray(page.usedComponents) ? page.usedComponents : [];
@@ -170,7 +189,11 @@ export function publicSiteSettings(site = {}) {
170
189
  if (site.footer && typeof site.footer === 'object') {
171
190
  out.footer = {...site.footer, links: (site.footer.links || []).filter(l => !l?.hidden)};
172
191
  }
173
- if (site.seo && typeof site.seo === 'object') out.seo = pick(site.seo, ['defaultTitle', 'titleSeparator', 'defaultDescription']);
192
+ if (site.seo && typeof site.seo === 'object') {
193
+ out.seo = pick(site.seo, ['defaultTitle', 'titleSeparator', 'defaultDescription']);
194
+ // As in the meta tag: a rich default description is given as its words.
195
+ if (isRichText(out.seo.defaultDescription)) out.seo.defaultDescription = richTextLine(out.seo.defaultDescription);
196
+ }
174
197
  return out;
175
198
  }
176
199
 
@@ -11,7 +11,7 @@ import * as cache from './cache/index.js';
11
11
  import {buttonSettingsProblems, formClassProblems} from '../../public/js/form-submit.mjs';
12
12
  import {fileIn} from './safePath.js';
13
13
  import {getConfig} from '../config.js';
14
- import {cleanRichText} from './richText.js';
14
+ import {cleanRichText, isRichText, renderRichTextPhrasing, richTextLine} from './richText.js';
15
15
 
16
16
  /** What one submission's files may hold in memory together when server.json sets nothing: 50 MB. */
17
17
  export const DEFAULT_MAX_SUBMISSION_BYTES = 50 * 1024 * 1024;
@@ -47,6 +47,61 @@ export function publicFileLimits(form) {
47
47
  return {...form, fileLimits: {maxTotalBytes: cap}};
48
48
  }
49
49
 
50
+ /** A wizard step's description and a chooser option's: rich text (richText.js), markup included. */
51
+ const STEP_DESCRIPTION_MAX = 2000;
52
+ const OPTION_DESCRIPTION_MAX = 1000;
53
+
54
+ /**
55
+ * A form's fields as they are stored: a step's description (a page-break
56
+ * field) and each option's description cleaned as rich text. A plain one is
57
+ * kept as typed; nothing else about a field is touched.
58
+ *
59
+ * @param {*} fields
60
+ * @returns {Array}
61
+ */
62
+ export function cleanFieldDescriptions(fields) {
63
+ if (!Array.isArray(fields)) return [];
64
+ return fields.map((f) => {
65
+ if (!f || typeof f !== 'object' || Array.isArray(f)) return f;
66
+ let next = f;
67
+ if (f.type === 'page-break' && typeof f.description === 'string') {
68
+ next = {...next, description: cleanRichText(f.description, {max: STEP_DESCRIPTION_MAX})};
69
+ }
70
+ if (Array.isArray(f.options) && f.options.some(o => o && typeof o === 'object' && typeof o.description === 'string')) {
71
+ next = {...next, options: f.options.map(o => (o && typeof o === 'object' && typeof o.description === 'string'
72
+ ? {...o, description: cleanRichText(o.description, {max: OPTION_DESCRIPTION_MAX})} : o))};
73
+ }
74
+ return next;
75
+ });
76
+ }
77
+
78
+ /**
79
+ * A form's descriptions as the page is given them. Domma draws both, and not
80
+ * the same way:
81
+ *
82
+ * - A step's description goes into the wizard's heading as HTML, inside a
83
+ * `<p>`. It is given as cleaned inline HTML (bold, italic, links; a
84
+ * paragraph or list item becomes a line break). A plain one written before
85
+ * descriptions were rich was drawn as HTML too, so inline markup typed by
86
+ * hand still works - and everything else in it is now dropped.
87
+ * - An option's description is drawn as text (the chooser sets textContent),
88
+ * so a rich one is given as its words.
89
+ *
90
+ * @param {object} form
91
+ * @returns {object}
92
+ */
93
+ export function publicFormDescriptions(form) {
94
+ if (!Array.isArray(form?.fields)) return form;
95
+ return {...form, fields: form.fields.map((f) => {
96
+ if (!f || typeof f !== 'object') return f;
97
+ if (f.type === 'page-break') {
98
+ return typeof f.description === 'string' ? {...f, description: renderRichTextPhrasing(f.description, {legacyHtml: true})} : f;
99
+ }
100
+ if (!Array.isArray(f.options) || !f.options.some(o => isRichText(o?.description))) return f;
101
+ return {...f, options: f.options.map(o => (isRichText(o?.description) ? {...o, description: richTextLine(o.description)} : o))};
102
+ })};
103
+ }
104
+
50
105
  /** The cache tag on every page that drew a form's file cap (markdown.js adds it). */
51
106
  export const FILE_LIMITS_TAG = 'forms:file-limits';
52
107
 
@@ -124,6 +179,7 @@ export async function writeForm(slug, data) {
124
179
  const {fileLimits: _limits, ...rest} = data;
125
180
  data = rest;
126
181
  }
182
+ if (data && Array.isArray(data.fields)) data = {...data, fields: cleanFieldDescriptions(data.fields)};
127
183
  const file = fileIn(FORMS_DIR, slug, '.json');
128
184
  await fs.writeFile(file, JSON.stringify(data, null, 4) + '\n', 'utf8');
129
185
  await cache.invalidateTags([`form:${slug}`]);
@@ -237,7 +293,7 @@ export async function createForm(data) {
237
293
  title: trimmedTitle,
238
294
  description: cleanRichText(description, {max: 4000}),
239
295
  ...(plugin ? {plugin} : {}),
240
- fields: Array.isArray(fields) ? fields : [],
296
+ fields: cleanFieldDescriptions(fields),
241
297
  settings: {
242
298
  submitText: 'Submit',
243
299
  successMessage: 'Thank you for your submission.',
@@ -11,6 +11,7 @@ import {getLastSendResult, isSmtpConfigured} from './email.js';
11
11
  import {listPages} from './content.js';
12
12
  import {getPluginLoadFailures} from './plugins.js';
13
13
  import {FORMS_DIR} from './forms.js';
14
+ import {richTextLine} from './richText.js';
14
15
 
15
16
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
16
17
  const ROOT = path.resolve(__dirname, '..', '..');
@@ -142,7 +143,8 @@ async function checkStalePages() {
142
143
 
143
144
  async function checkMissingMeta() {
144
145
  const pages = await listPages({render: false}).catch(() => []);
145
- const missing = pages.filter(p => !p.description || String(p.description).trim() === '');
146
+ // Judged on its words: an emptied rich editor's markup is not a description.
147
+ const missing = pages.filter(p => !richTextLine(p.description));
146
148
  return {
147
149
  id: 'missing-meta',
148
150
  level: missing.length === 0 ? 'ok' : 'warn',
@@ -27,7 +27,7 @@ import {buildTextStyle, buildTextMotion} from '../../public/js/text-style.mjs';
27
27
  import {buildScribeStyle} from '../../public/js/scribe-style.mjs';
28
28
  import {CHARACTERS, resolveCharacterSize} from '../../public/js/celebrations/character-catalog.mjs';
29
29
  import {publicButtonSettings} from '../../public/js/form-submit.mjs';
30
- import {FILE_LIMITS_TAG, publicFileLimits} from './forms.js';
30
+ import {FILE_LIMITS_TAG, publicFileLimits, publicFormDescriptions} from './forms.js';
31
31
  import {applyShortcodeExpiry} from './shortcodeExpiry.js';
32
32
  import {richTextToPlain} from '../../public/js/rich-text.mjs';
33
33
 
@@ -5105,7 +5105,7 @@ async function processFormBlocks(markdown, tagSet) {
5105
5105
  const {actions: _actions, ...publicForm} = form;
5106
5106
  // A Cancel link that is not safe to draw stays out of the page source.
5107
5107
  if (publicForm.settings) publicForm.settings = publicButtonSettings(publicForm.settings);
5108
- const drawn = publicFileLimits(publicForm);
5108
+ const drawn = publicFileLimits(publicFormDescriptions(publicForm));
5109
5109
  if (drawn.fileLimits) tagSet?.add(FILE_LIMITS_TAG);
5110
5110
  const encoded = Buffer.from(JSON.stringify(drawn)).toString('base64');
5111
5111
  const extraClass = attrs.class ? ` ${escapeAttr(attrs.class)}` : '';
@@ -23,8 +23,8 @@ import {
23
23
  PRESET_COLOUR_VARS, PRESET_COLOUR_FALLBACKS, colourToCss, cssClassProblems
24
24
  } from '../../public/js/menu-decor.mjs';
25
25
  import {fileIn} from './safePath.js';
26
- import {normaliseLook, lookProblems, itemLookProblems} from '../../public/js/menu-look.mjs';
27
- import {cleanRichText} from './richText.js';
26
+ import {normaliseLook, lookProblems, itemLookProblems, DESCRIPTION_MARKUP_MAX} from '../../public/js/menu-look.mjs';
27
+ import {cleanRichText, isRichText, renderRichTextPhrasing, richTextLine} from './richText.js';
28
28
 
29
29
  export {normaliseLook};
30
30
 
@@ -457,8 +457,13 @@ export async function resolveMenuDecorations(items, opts = {}) {
457
457
 
458
458
  async function walk(list) {
459
459
  return Promise.all((list || []).map(async (it) => {
460
- if (!it || isStructuralItem(it)) return it;
461
- const next = {...it};
460
+ if (!it) return it;
461
+ if (isStructuralItem(it)) {
462
+ if (!('descriptionHtml' in it)) return it;
463
+ const {descriptionHtml: _forged, ...rest} = it;
464
+ return rest;
465
+ }
466
+ const next = servedDescription({...it});
462
467
  if (it.badge && it.badge.countFrom) {
463
468
  try {
464
469
  const n = await countEntries(it.badge.countFrom);
@@ -475,6 +480,51 @@ export async function resolveMenuDecorations(items, opts = {}) {
475
480
  return walk(items);
476
481
  }
477
482
 
483
+ /**
484
+ * An item's card caption (`description`) as the page is given it. The caption
485
+ * is rich text, and menu JSON is hand-editable, so what is stored is not
486
+ * trusted here: a rich caption goes out as `description` (its words, for
487
+ * anything that draws text) plus `descriptionHtml`, cleaned to inline
488
+ * formatting - it is drawn inside the entry's link, so no blocks and no links.
489
+ * A plain caption is left as it is and drawn as text. `descriptionHtml` is
490
+ * never taken from the file: only this function writes it.
491
+ *
492
+ * @param {object} item - a copy, changed and returned
493
+ * @returns {object}
494
+ */
495
+ function servedDescription(item) {
496
+ delete item.descriptionHtml;
497
+ if (!isRichText(item.description)) return item;
498
+ const html = renderRichTextPhrasing(item.description, {links: false});
499
+ item.description = richTextLine(item.description);
500
+ if (html) item.descriptionHtml = html;
501
+ return item;
502
+ }
503
+
504
+ /**
505
+ * A menu's items as they are stored: each caption cleaned as rich text
506
+ * (richText.js) and any `descriptionHtml` dropped - that key is only ever
507
+ * made on the way out, by resolveMenuDecorations. Everything else is left
508
+ * exactly as sent; validateMenu has already judged it.
509
+ *
510
+ * @param {*} items
511
+ * @returns {Array}
512
+ */
513
+ export function cleanItemDescriptions(items) {
514
+ if (!Array.isArray(items)) return [];
515
+ return items.map((it) => {
516
+ if (!it || typeof it !== 'object' || Array.isArray(it)) return it;
517
+ const {descriptionHtml: _made, ...next} = it;
518
+ if (typeof next.description === 'string') {
519
+ const cleaned = cleanRichText(next.description, {max: DESCRIPTION_MARKUP_MAX});
520
+ if (cleaned) next.description = cleaned;
521
+ else delete next.description;
522
+ }
523
+ if (Array.isArray(next.items)) next.items = cleanItemDescriptions(next.items);
524
+ return next;
525
+ });
526
+ }
527
+
478
528
  /**
479
529
  * Ensure MENUS_DIR exists. Safe to call repeatedly.
480
530
  *
@@ -634,7 +684,7 @@ export async function createMenu(input) {
634
684
  ...(normaliseMobile(input.mobile) && {mobile: normaliseMobile(input.mobile)}),
635
685
  ...(normaliseLook(input.look) && {look: normaliseLook(input.look)}),
636
686
  ...(binding != null && {binding}),
637
- items: Array.isArray(input.items) ? input.items : [],
687
+ items: cleanItemDescriptions(input.items),
638
688
  meta: {
639
689
  createdAt: now,
640
690
  updatedAt: now,
@@ -708,7 +758,7 @@ export async function updateMenu(slug, input, opts = {}) {
708
758
  ...(normaliseMobile(input.mobile) && {mobile: normaliseMobile(input.mobile)}),
709
759
  ...(normaliseLook(input.look) && {look: normaliseLook(input.look)}),
710
760
  ...(binding != null && {binding}),
711
- items: Array.isArray(input.items) ? input.items : [],
761
+ items: cleanItemDescriptions(input.items),
712
762
  meta: {
713
763
  ...existing.meta,
714
764
  ...(input.meta || {}),
@@ -11,6 +11,7 @@ import {getInjectionSnippets} from './plugins.js';
11
11
  import {applyTransforms} from './hooks.js';
12
12
  import {contentsPaint, readContentsOverride, resolveContents} from './pageContents.js';
13
13
  import {applyMenuOverride, hasThemeSwitcherItem, resolveLocation, resolveMenuDecorations, resolveOverlaysForPage} from './menus.js';
14
+ import {isRichText, richTextLine} from './richText.js';
14
15
  import {buildMenuNav} from './menuRender.js';
15
16
  import {buildFooterFallback, buildNavFallback} from './nojsLinks.js';
16
17
  import {getProjectForPage} from './projects.js';
@@ -818,7 +819,7 @@ function buildSeoMeta({page, site, baseUrl, title, description, image}) {
818
819
  '@context': 'https://schema.org',
819
820
  '@type': 'WebPage',
820
821
  name: page.title || '',
821
- description: page.seo?.description || site.seo?.defaultDescription || ''
822
+ description: richTextLine(page.seo?.description || site.seo?.defaultDescription || '')
822
823
  };
823
824
  if (canonical) webPage.url = canonical;
824
825
  if (absImage) webPage.image = absImage;
@@ -848,7 +849,8 @@ function buildSeoMeta({page, site, baseUrl, title, description, image}) {
848
849
 
849
850
  return {
850
851
  title,
851
- description,
852
+ // An SEO description may be rich text (the editor's); a tag holds its words.
853
+ description: richTextLine(description),
852
854
  image: absImage,
853
855
  ogType: page.seo?.ogType || 'article',
854
856
  noindex: page.seo?.noindex === true,
@@ -902,13 +904,35 @@ function absoluteUrl(url, origin) {
902
904
  function transformSeoMeta(meta, context) {
903
905
  try {
904
906
  const out = applyTransforms('seo:meta', meta, context);
905
- return out && typeof out === 'object' ? out : meta;
907
+ return plainSeoDescriptions(out && typeof out === 'object' ? out : meta);
906
908
  } catch (err) {
907
909
  console.warn(`[seo] a seo:meta transform failed, using the page's own: ${err.message}`);
908
- return meta;
910
+ return plainSeoDescriptions(meta);
909
911
  }
910
912
  }
911
913
 
914
+ /**
915
+ * Every description in the SEO model as one line of plain text. The SEO
916
+ * description fields are rich text editors, and a transform (the SEO Tool's
917
+ * per-address override, a plugin's own) may hand a rich value back: a meta
918
+ * tag, a share card and JSON-LD carry the words, never the markup. A value
919
+ * that is not rich is left exactly as it is. Pure.
920
+ *
921
+ * @param {object} meta - buildSeoMeta()'s model
922
+ * @returns {object}
923
+ */
924
+ export function plainSeoDescriptions(meta) {
925
+ const line = (v) => (isRichText(v) ? richTextLine(v) : v);
926
+ const part = (o) => (o && typeof o === 'object' && isRichText(o.description) ? {...o, description: line(o.description)} : o);
927
+ return {
928
+ ...meta,
929
+ description: line(meta.description),
930
+ og: part(meta.og),
931
+ twitter: part(meta.twitter),
932
+ ...(Array.isArray(meta.jsonLd) && {jsonLd: meta.jsonLd.map(part)})
933
+ };
934
+ }
935
+
912
936
  const SAFE_ATTR = /^[a-z][a-z0-9:_-]*$/i;
913
937
 
914
938
  /**
@@ -10,8 +10,12 @@
10
10
  * HTML email. A rich value is cleaned again (what is stored may predate a
11
11
  * rule, or have been written around the API); a plain one is escaped into
12
12
  * paragraphs. Its result is always safe to put in a page.
13
- * - `richTextToPlain` / `richTextSummary` (re-exported) for everything that is
14
- * not HTML: meta descriptions, plain emails, CSV, ICS, search, JSON-LD.
13
+ * - `renderRichTextPhrasing(value)` where a description is drawn INSIDE a
14
+ * line of text (a `<p>`, a link, a button): the same words with only inline
15
+ * formatting, so it cannot break the element it sits in.
16
+ * - `richTextToPlain` / `richTextSummary` / `richTextLine` (re-exported) for
17
+ * everything that is not HTML: meta descriptions, plain emails, CSV, ICS,
18
+ * search, JSON-LD.
15
19
  *
16
20
  * Deliberately far stricter than `sanitizePageHtml`: a description is a few
17
21
  * formatted paragraphs, not a page. No images, classes, styles or embeds.
@@ -19,7 +23,7 @@
19
23
  * @module server/services/richText
20
24
  */
21
25
  import sanitizeHtml from 'sanitize-html';
22
- import {isRichText, plainToRichHtml, richTextToPlain, richTextSummary, escapeHtml} from '../../public/js/rich-text.mjs';
26
+ import {isRichText, plainToRichHtml, richTextToPlain, richTextSummary, richTextLine as plainLine, escapeHtml} from '../../public/js/rich-text.mjs';
23
27
 
24
28
  export {isRichText, plainToRichHtml, richTextToPlain, richTextSummary};
25
29
 
@@ -96,3 +100,52 @@ export function renderRichText(value) {
96
100
  export function renderRichTextInline(value, max = 160) {
97
101
  return escapeHtml(richTextSummary(value, max));
98
102
  }
103
+
104
+ /**
105
+ * A description as one line of plain text, not cut: for a meta description, a
106
+ * JSON-LD value, an llms.txt line, a search result. A rich value is cleaned
107
+ * first - what is stored may have been written by hand, and the text inside a
108
+ * `<script>` is not one of its words. A plain value is returned as stored
109
+ * (trimmed).
110
+ *
111
+ * @param {*} value - as stored
112
+ * @returns {string}
113
+ */
114
+ export function richTextLine(value) {
115
+ return plainLine(isRichText(value) ? clean(value) : value);
116
+ }
117
+
118
+ /** What may sit inside a line of text: no blocks, no lists. */
119
+ const PHRASING_TAGS = ['strong', 'b', 'em', 'i', 'u', 's', 'code', 'br'];
120
+
121
+ /**
122
+ * A description as HTML that is safe to put INSIDE a line of text - a `<p>`,
123
+ * a link, a button, a caption - where a paragraph or a list would break the
124
+ * element around it. Paragraphs and list items become line breaks (a list
125
+ * item starts "- "), headings and quotes lose their element and keep their
126
+ * words, and only inline formatting is left.
127
+ *
128
+ * A rich value is cleaned first. A plain value is escaped, unless `legacyHtml`
129
+ * is set: for a field whose plain text was drawn as HTML before it was rich,
130
+ * so inline markup somebody typed by hand keeps working and anything else in
131
+ * it (scripts, images, event handlers) is dropped.
132
+ *
133
+ * @param {*} value - as stored
134
+ * @param {{links?: boolean, legacyHtml?: boolean}} [options] - `links: false`
135
+ * where the text sits inside a link already
136
+ * @returns {string} '' for nothing
137
+ */
138
+ export function renderRichTextPhrasing(value, {links = true, legacyHtml = false} = {}) {
139
+ if (typeof value !== 'string' || !value.trim()) return '';
140
+ const rich = isRichText(value);
141
+ if (!rich && !legacyHtml) return escapeHtml(value.trim()).replace(/\r\n?|\n/g, '<br>');
142
+ const flat = (rich ? clean(value) : value.trim())
143
+ .replace(/<li(\s[^<>]*)?>/gi, '- ')
144
+ .replace(/<\/(p|h[1-6]|blockquote|li|ul|ol|div)>/gi, '<br>');
145
+ const out = sanitizeHtml(flat, {
146
+ ...OPTIONS,
147
+ allowedTags: links ? [...PHRASING_TAGS, 'a'] : PHRASING_TAGS,
148
+ transformTags: {a: OPTIONS.transformTags.a}
149
+ });
150
+ return out.replace(/<br \/>/g, '<br>').replace(/(\s*<br>\s*){2,}/g, '<br>').replace(/^(\s|<br>)+|(\s|<br>)+$/g, '');
151
+ }
@@ -12,6 +12,7 @@
12
12
  import {getConfig, saveConfig} from '../config.js';
13
13
  import {checkVisibility} from '../middleware/auth.js';
14
14
  import {normalisePath} from '../../admin/js/lib/seo-redirects.js';
15
+ import {richTextLine} from './richText.js';
15
16
 
16
17
  /**
17
18
  * Settings, and the shape of them.
@@ -318,7 +319,8 @@ function buildSnippet(rawContent, term, length = 120) {
318
319
  export function scorePage(page, query, words) {
319
320
  let score = 0;
320
321
  const title = (page.title || '').toLowerCase();
321
- const description = (page.description || '').toLowerCase();
322
+ // The words alone: a rich description is not matched on its markup.
323
+ const description = richTextLine(page.description).toLowerCase();
322
324
  // Coerced, not trusted. A tag list is `Array.isArray` true and still full
323
325
  // of nulls - `tags:\n - null` is what a page ends up with when something
324
326
  // writes an empty tag - and `null.toLowerCase()` threw, which took the
@@ -519,7 +521,8 @@ export function searchPages(pages, query, {maxResults = 10, onError = () => {},
519
521
  results.push({
520
522
  title: page.title || 'Untitled',
521
523
  url: page.urlPath,
522
- description: page.description || '',
524
+ // Results are drawn as text (the site's search box, the Content API).
525
+ description: richTextLine(page.description),
523
526
  tags: Array.isArray(page.tags) ? page.tags : [],
524
527
  snippet: buildSnippet(page.content || '', query),
525
528
  score
@@ -11,6 +11,7 @@ import {listPages} from './content.js';
11
11
  import {offlinePageUrls} from './projects.js';
12
12
  import {getConfig} from '../config.js';
13
13
  import {applyTransforms, getSitemapSources} from './hooks.js';
14
+ import {richTextLine} from './richText.js';
14
15
 
15
16
  const CHANGEFREQ = new Set(['always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never']);
16
17
  const validPriority = (p) => p !== undefined && p !== null && p !== '' && Number(p) >= 0 && Number(p) <= 1;
@@ -37,7 +38,8 @@ function shouldIncludeInSitemap(page) {
37
38
 
38
39
  /** The sitemap entry of a core page. `description` is for llms.txt; the XML ignores it. */
39
40
  function pageEntry(page) {
40
- const description = String(page.seo?.description || page.description || '').trim();
41
+ // Either may be rich text (the editors'): llms.txt is plain text.
42
+ const description = richTextLine(page.seo?.description || page.description || '');
41
43
  return {urlPath: page.urlPath, title: page.title || '', lastmod: page.updatedAt || null,
42
44
  ...(description && {description}), source: 'pages'};
43
45
  }
@@ -197,7 +199,7 @@ export async function buildLlmsTxt(baseUrl, opts = {}) {
197
199
  const labels = new Map(getSitemapSources().map(s => [s.id, s.label || s.id]));
198
200
 
199
201
  const title = oneLine(site.title || site.seo?.defaultTitle || 'Website');
200
- const description = oneLine(site.seo?.defaultDescription || site.description || '');
202
+ const description = oneLine(richTextLine(site.seo?.defaultDescription || site.description || ''));
201
203
  const out = [`# ${title}`, ''];
202
204
  if (description) out.push(`> ${description}`, '');
203
205
 
@@ -213,7 +215,7 @@ export async function buildLlmsTxt(baseUrl, opts = {}) {
213
215
  for (const e of list) {
214
216
  const url = `${normalised}${e.urlPath}`;
215
217
  const name = linkText(e.title || e.urlPath);
216
- const about = oneLine(e.description || '');
218
+ const about = oneLine(richTextLine(e.description || ''));
217
219
  out.push(`- [${name}](${linkUrl(url)})${about ? `: ${about}` : ''}`);
218
220
  }
219
221
  out.push('');
@@ -189,7 +189,7 @@
189
189
  <script src="/public/js/form-logic-engine.js?v=20261031-forms-reduce-motion" defer></script>
190
190
 
191
191
  <!-- Site initialisation -->
192
- <script src="/public/js/site.js?v=20261112-card-body-align" type="module"></script>
192
+ <script src="/public/js/site.js?v=20261115-rich-captions" type="module"></script>
193
193
  <script src="/public/js/collection-context.js?v=20261010-utf8-payloads" type="module"></script>
194
194
  {{ctxMenusModule}}
195
195
  <!-- [image zoom] pictures' full-size view - only on a page that has one -->