@crossworks/content-core 0.232.369 → 0.232.375

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossworks/content-core",
-  "version": "0.232.369",
+  "version": "0.232.375",
   "description": "Browser-safe content logic — markdown, blocks, pages, tables, formulas — shared by the server and any client. Zero server deps by design: nothing here may reach @mantle/db, node-only APIs, or the network (the jackdaw-repo-split P0 boundary).",
   "exports": {
     "./app-nav": "./src/app-nav.ts",
@@ -17,6 +17,7 @@
     "./journal-options": "./src/journal-options.ts",
     "./markdown": "./src/markdown-to-doc.ts",
     "./markdown-refs": "./src/markdown-refs.ts",
+    "./markdown-to-text": "./src/markdown-to-text.ts",
     "./onboarding-questions": "./src/onboarding-questions.ts",
     "./page-diff": "./src/page-diff.ts",
     "./page-split": "./src/page-split.ts",
@@ -31,7 +32,7 @@
     "./tree": "./src/tree.ts"
   },
   "dependencies": {
-    "@mantle/client-types": "npm:@crossworks/client-types@0.232.369",
+    "@mantle/client-types": "npm:@crossworks/client-types@0.232.375",
     "marked": "^18.0.11",
     "mathjs": "15.2.0"
   },

package/src/markdown-to-text.test.ts

@@ -0,0 +1,119 @@
+// markdownToPlainText / markdownPreview: what a push notification's
+// lock-screen line shows of a reply. Real reply shapes, mark by mark.
+
+import { describe, expect, it } from 'vitest';
+import { markdownPreview, markdownToPlainText } from './markdown-to-text';
+
+const plain = markdownToPlainText;
+
+describe('markdownToPlainText', () => {
+  it('a heading, bold, italic, strike and highlight keep their words only', () => {
+    expect(plain('## Summary\n\nThe **pump** spec is _ready_, ~~not late~~ ==today==.')).toBe(
+      'Summary The pump spec is ready, not late today.',
+    );
+    expect(plain('# Title\ntext')).toBe('Title text');
+  });
+
+  it('a list loses its markers, a to-do its box, a quote its mark', () => {
+    expect(plain('- one\n- two\n  - nested\n\n1. first\n2. second')).toBe(
+      'one two nested first second',
+    );
+    expect(plain('- [x] booked flights\n- [ ] book hotel')).toBe('booked flights book hotel');
+    expect(plain('> quoted line\n\nafter')).toBe('quoted line after');
+  });
+
+  it('a link keeps its text, never its address', () => {
+    const out = plain(
+      'See [the docs](https://example.invalid/x?y=1) and <https://example.invalid/z>.',
+    );
+    expect(out).toContain('See the docs and');
+    expect(out).not.toContain('](');
+    expect(out).not.toContain('x?y=1');
+  });
+
+  it('a reference chip keeps its label and drops its target', () => {
+    const id = '11111111-1111-4111-8111-111111111111';
+    const out = plain(
+      `Open [Pump spec](page:${id}), ask [Ada](mention:entity:${id}), read [the file](media:${id}).`,
+    );
+    expect(out).toContain('Pump spec');
+    expect(out).toContain('Ada');
+    expect(out).toContain('the file');
+    expect(out).not.toContain(id);
+    expect(out).not.toMatch(/page:|mention:|media:|\]\(/);
+  });
+
+  it('an image and a drawing leave their alt text or nothing, never a path', () => {
+    const id = '22222222-2222-4222-8222-222222222222';
+    const out = plain(`Here ![the chart](media:${id}) and ![](draw:${id}) end`);
+    expect(out).not.toContain(id);
+    expect(out).not.toMatch(/!\[|media:|draw:|\/api\//);
+    expect(out.startsWith('Here')).toBe(true);
+    expect(out.endsWith('end')).toBe(true);
+    expect(plain(`![chart](/api/member/files/${id})`)).not.toContain('/api/');
+  });
+
+  it('code keeps its text and loses its marks and its language', () => {
+    expect(plain('Run this:\n```bash\npnpm verify\n```\nthen `git status`.')).toBe(
+      'Run this: pnpm verify then git status.',
+    );
+  });
+
+  it('a table keeps its cell text', () => {
+    const out = plain('| Item | Qty |\n|---|---|\n| Pump | 2 |\n| Valve | 5 |');
+    expect(out).toBe('Item Qty Pump 2 Valve 5');
+  });
+
+  it('math keeps its source without the marks; a rule says nothing', () => {
+    const out = plain('Area $x^2$ here\n\n---\n\nend');
+    expect(out).not.toContain('$');
+    expect(out).not.toContain('---');
+    expect(out).toContain('x^2');
+    expect(out.endsWith('end')).toBe(true);
+  });
+
+  it('a callout and columns keep their text, not their fences', () => {
+    const out = plain(':::info\nMind the gap\n:::\n\n:::columns\nleft\n+++\nright\n:::');
+    expect(out).toContain('Mind the gap');
+    expect(out).toContain('left');
+    expect(out).toContain('right');
+    expect(out).not.toContain(':::');
+    expect(out).not.toContain('+++');
+  });
+
+  it('raw HTML tags go, their words stay', () => {
+    expect(plain('a <b>bold</b> word<br>next')).toBe('a bold word next');
+  });
+
+  it('plain text comes back as it is, on one line', () => {
+    expect(plain('  We fixed the date.\n\nSee you at 2 * 3 pm, snake_case_name stays.  ')).toBe(
+      'We fixed the date. See you at 2 * 3 pm, snake_case_name stays.',
+    );
+  });
+
+  it('nothing in, nothing out', () => {
+    expect(plain('')).toBe('');
+    expect(plain('   \n ')).toBe('');
+    expect(plain('---')).toBe('');
+    expect(plain(undefined as unknown as string)).toBe('');
+  });
+});
+
+describe('markdownPreview', () => {
+  it('cuts after the marks are gone, so no half mark is left at the end', () => {
+    const out = markdownPreview(`## ${'**word** '.repeat(60)}`, 140);
+    expect(out).toHaveLength(140);
+    expect(out.endsWith('…')).toBe(true);
+    expect(out).not.toMatch(/[*#]/);
+  });
+
+  it('is empty for a text with no words, so the caller can say something generic', () => {
+    expect(markdownPreview('![](media:abc)')).toBe('');
+    expect(markdownPreview('```\n```')).toBe('');
+  });
+
+  it('reads only the start of a very long text', () => {
+    const out = markdownPreview(`${'a '.repeat(10_000)}**end**`, 50);
+    expect(out).toHaveLength(50);
+  });
+});

package/src/markdown-to-text.ts

@@ -0,0 +1,97 @@
+/**
+ * markdownToPlainText: the words of a rich-markdown text with every mark
+ * gone, on one line. For places that show a reply where nothing renders
+ * markdown: a push notification's lock-screen line, a list preview.
+ *
+ * It reads the text with the SAME parser the rest of the brain uses for the
+ * dialect (`markdownToDoc`: GFM plus callouts, columns, highlights, math and
+ * the reference chips), then keeps the words:
+ *
+ *   headings, bold, italic, strike, highlight, colour   the text
+ *   a link, a reference chip (`page:`, `media:`,
+ *     `mention:`, `folder:`, `draw:`)                   its label, never its target
+ *   an image or an embedded drawing                     its alt text, else nothing
+ *   inline code and a code fence                        the code text (a short
+ *                                                       command is the useful part)
+ *   lists, block quotes, callouts, columns              their text, no markers
+ *   a table                                             its cell text
+ *   math                                                its source, no `$`
+ *   a rule, a diagram, a folder index                   nothing
+ *
+ * Pure and browser-safe (only `marked`, through markdownToDoc). Never throws:
+ * a text the parser cannot read comes back with its whitespace collapsed.
+ */
+import { markdownToDoc } from './markdown-to-doc';
+
+type PMNode = {
+  type?: string;
+  text?: string;
+  attrs?: Record<string, unknown>;
+  content?: PMNode[];
+};
+
+/** How much of a text is read: a preview needs its start only. */
+const READ_MAX = 4000;
+
+/** What a childless node (a chip, an image, math) says, in this order. */
+const LABEL_KEYS = ['label', 'title', 'alt', 'name', 'filename', 'latex'];
+
+/** Nodes that say nothing in a preview. `diagram` holds source code of a
+ *  picture; `folderIndex` is a live list, none of it this text's own words. */
+const SILENT = new Set(['horizontalRule', 'diagram', 'folderIndex']);
+
+function render(node: PMNode | null | undefined, out: string[]): void {
+  if (!node || typeof node !== 'object') return;
+  if (node.type && SILENT.has(node.type)) return;
+  if (typeof node.text === 'string') {
+    out.push(node.text);
+    return;
+  }
+  if (node.type === 'hardBreak') {
+    out.push(' ');
+    return;
+  }
+  const kids = Array.isArray(node.content) ? node.content : [];
+  if (kids.length === 0) {
+    const attrs = node.attrs ?? {};
+    for (const key of LABEL_KEYS) {
+      const v = attrs[key];
+      if (typeof v === 'string' && v.trim()) {
+        out.push(v);
+        break;
+      }
+    }
+    out.push(' ');
+    return;
+  }
+  for (const k of kids) render(k, out);
+  // Every node with children is a block or a wrapper: its text never runs
+  // into what follows.
+  out.push(' ');
+}
+
+const oneLine = (s: string) => s.replace(/\s+/g, ' ').trim();
+
+/** The words of `source` on one line; '' when it has none. */
+export function markdownToPlainText(source: string): string {
+  if (typeof source !== 'string' || !source.trim()) return '';
+  const text = source.length > READ_MAX ? source.slice(0, READ_MAX) : source;
+  try {
+    const out: string[] = [];
+    render(markdownToDoc(text) as PMNode, out);
+    // Raw HTML the dialect does not map arrives as text: drop the tags.
+    return oneLine(out.join('').replace(/<\/?[a-zA-Z][^<>]*>/g, ' '));
+  } catch {
+    return oneLine(text);
+  }
+}
+
+/**
+ * A preview line: the plain words of `source`, cut to `max` characters with
+ * an ellipsis. '' when the text has no words (the caller says something
+ * generic instead: a preview is never empty and never raw markdown).
+ */
+export function markdownPreview(source: string, max = 140): string {
+  const plain = markdownToPlainText(source);
+  return plain.length > max ? `${plain.slice(0, max - 1)}…` : plain;
+}