@tiaforge-ui/sinter-markdown 0.0.0-stage → 0.20.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 (36) hide show
  1. package/README.md +305 -2
  2. package/docs/markdown.md +258 -0
  3. package/docs/recipes/article-with-comments.html +28 -0
  4. package/llms.txt +44 -0
  5. package/package.json +65 -4
  6. package/sinter/components/internal/md-block.html +7 -0
  7. package/sinter/components/internal/md-blockquote.html +3 -0
  8. package/sinter/components/internal/md-break.html +3 -0
  9. package/sinter/components/internal/md-code.html +4 -0
  10. package/sinter/components/internal/md-delete.html +3 -0
  11. package/sinter/components/internal/md-details.html +4 -0
  12. package/sinter/components/internal/md-emphasis.html +3 -0
  13. package/sinter/components/internal/md-heading.html +4 -0
  14. package/sinter/components/internal/md-image.html +9 -0
  15. package/sinter/components/internal/md-inline-code.html +3 -0
  16. package/sinter/components/internal/md-kbd.html +3 -0
  17. package/sinter/components/internal/md-link.html +4 -0
  18. package/sinter/components/internal/md-list-item.html +4 -0
  19. package/sinter/components/internal/md-list.html +4 -0
  20. package/sinter/components/internal/md-mark.html +3 -0
  21. package/sinter/components/internal/md-paragraph.html +3 -0
  22. package/sinter/components/internal/md-phrasing.html +9 -0
  23. package/sinter/components/internal/md-strong.html +3 -0
  24. package/sinter/components/internal/md-sub.html +3 -0
  25. package/sinter/components/internal/md-sup.html +3 -0
  26. package/sinter/components/internal/md-table.html +9 -0
  27. package/sinter/components/internal/md-thematic-break.html +3 -0
  28. package/sinter/components/md-doc.html +10 -0
  29. package/sinter/components/md-inline.html +11 -0
  30. package/sinter/index.ts +5 -0
  31. package/sinter/parse.ts +270 -0
  32. package/sinter/parser.d.ts +19 -0
  33. package/sinter/parser.js +2872 -0
  34. package/sinter/sinter.helpers.ts +10 -0
  35. package/sinter/sinter.types.ts +209 -0
  36. package/sinter/tree.ts +61 -0
@@ -0,0 +1,10 @@
1
+ // The library's helpers, in two modules under one namespace. An app re-exports the package as a
2
+ // namespace (`export * as md from '@tiaforge-ui/sinter-markdown'` in its src/sinter.helpers.ts) and calls
3
+ // `md.parse`, `md.headings` and `md.text` in markup.
4
+ //
5
+ // - parse.ts imports the parser. An app that lists the parser's package in `sinter({ lazy })` makes it
6
+ // load when a let first needs it; the let waits for it.
7
+ // - tree.ts reads a parsed tree and imports no parser, so `md.headings` and `md.text` stay ordinary
8
+ // helpers either way: they render early and fold at build time.
9
+ export { parse } from './parse.js';
10
+ export { headings, text } from './tree.js';
@@ -0,0 +1,209 @@
1
+ // The tree `md.parse` returns and the md-* components render: mdast (https://github.com/syntax-tree/mdast),
2
+ // reduced to what the components draw. Every node is plain data (no positions, no `data`), so a tree
3
+ // folds at build time, travels as JSON from an API, and is checked by `type` in markup:
4
+ // `{ paragraph: 'md-paragraph', heading: 'md-heading' }[node.type]`.
5
+ //
6
+ // Where it differs from mdast:
7
+ // - definitions are resolved: `linkReference` and `imageReference` are `link` and `image`;
8
+ // - a heading has a `slug`, and its anchor is `md-` + slug, the id `md.headings` lists;
9
+ // - a list's `spread` is whether it renders loose (`<p>` in its items), as mdast-util-to-hast decides it;
10
+ // - raw HTML is never an `html` node: it is text, dropped, or one of the elements `html: 'allow'` keeps
11
+ // (`kbd`, `sub`, `sup`, `mark`, `details`).
12
+
13
+ /** a parsed document */
14
+ export interface Root {
15
+ type: 'root';
16
+ children: Block[];
17
+ }
18
+
19
+ /** block content: what `md-doc` renders */
20
+ export type Block = Paragraph | Heading | ThematicBreak | Blockquote | List | Code | Table | Details;
21
+
22
+ /** phrasing content: the inside of a paragraph, a heading, a table cell */
23
+ export type Inline = Text | Emphasis | Strong | Delete | InlineCode | Break | Link | Image | Kbd | Sub | Sup | Mark;
24
+
25
+ /** phrasing content other than a text run: what `md-phrasing` dispatches to its component */
26
+ export type Phrasing = Exclude<Inline, Text>;
27
+
28
+ /** any node of the tree */
29
+ export type MdNode = Root | Block | Inline | ListItem | TableRow | TableCell;
30
+
31
+ export interface Paragraph {
32
+ type: 'paragraph';
33
+ children: Inline[];
34
+ }
35
+
36
+ export interface Heading {
37
+ type: 'heading';
38
+ depth: 1 | 2 | 3 | 4 | 5 | 6;
39
+ /**
40
+ * From the heading's text (`## Getting started` → `getting-started`), unique in the document. The
41
+ * heading's anchor is `md-` + slug (`id="md-getting-started"`), the id `md.headings` gives: an id
42
+ * written from data starts with a literal, so it cannot clobber a global (sinter's SN503).
43
+ */
44
+ slug: string;
45
+ children: Inline[];
46
+ }
47
+
48
+ export interface ThematicBreak {
49
+ type: 'thematicBreak';
50
+ }
51
+
52
+ export interface Blockquote {
53
+ type: 'blockquote';
54
+ children: Block[];
55
+ }
56
+
57
+ export interface List {
58
+ type: 'list';
59
+ ordered: boolean;
60
+ /** the first number of an ordered list, null for an unordered one */
61
+ start: number | null;
62
+ /** loose: its items' paragraphs render as `<p>` */
63
+ spread: boolean;
64
+ children: ListItem[];
65
+ }
66
+
67
+ export interface ListItem {
68
+ type: 'listItem';
69
+ /** a task: `[x]` is true, `[ ]` false; null when the item is no task */
70
+ checked: boolean | null;
71
+ children: Block[];
72
+ }
73
+
74
+ export interface Code {
75
+ type: 'code';
76
+ /** the info string's first word (` ```ts ` → `ts`), or null */
77
+ lang: string | null;
78
+ /** the rest of the info string, or null */
79
+ meta: string | null;
80
+ value: string;
81
+ }
82
+
83
+ export type Align = 'left' | 'right' | 'center' | null;
84
+
85
+ export interface Table {
86
+ type: 'table';
87
+ /** per column */
88
+ align: Align[];
89
+ /** the first row is the header */
90
+ children: TableRow[];
91
+ }
92
+
93
+ export interface TableRow {
94
+ type: 'tableRow';
95
+ children: TableCell[];
96
+ }
97
+
98
+ export interface TableCell {
99
+ type: 'tableCell';
100
+ children: Inline[];
101
+ }
102
+
103
+ /** `<details>` with its `<summary>`, from raw HTML under `html: 'allow'` */
104
+ export interface Details {
105
+ type: 'details';
106
+ open: boolean;
107
+ /** the summary's content; empty when there is no `<summary>` */
108
+ summary: Inline[];
109
+ children: Block[];
110
+ }
111
+
112
+ export interface Text {
113
+ type: 'text';
114
+ value: string;
115
+ }
116
+
117
+ export interface Emphasis {
118
+ type: 'emphasis';
119
+ children: Inline[];
120
+ }
121
+
122
+ export interface Strong {
123
+ type: 'strong';
124
+ children: Inline[];
125
+ }
126
+
127
+ /** `~~strikethrough~~` */
128
+ export interface Delete {
129
+ type: 'delete';
130
+ children: Inline[];
131
+ }
132
+
133
+ export interface InlineCode {
134
+ type: 'inlineCode';
135
+ value: string;
136
+ }
137
+
138
+ /** a hard line break */
139
+ export interface Break {
140
+ type: 'break';
141
+ }
142
+
143
+ export interface Link {
144
+ type: 'link';
145
+ url: string;
146
+ title: string | null;
147
+ children: Inline[];
148
+ }
149
+
150
+ export interface Image {
151
+ type: 'image';
152
+ url: string;
153
+ title: string | null;
154
+ alt: string;
155
+ }
156
+
157
+ /** `<kbd>`, under `html: 'allow'` */
158
+ export interface Kbd {
159
+ type: 'kbd';
160
+ children: Inline[];
161
+ }
162
+
163
+ /** `<sub>`, under `html: 'allow'` */
164
+ export interface Sub {
165
+ type: 'sub';
166
+ children: Inline[];
167
+ }
168
+
169
+ /** `<sup>`, under `html: 'allow'` */
170
+ export interface Sup {
171
+ type: 'sup';
172
+ children: Inline[];
173
+ }
174
+
175
+ /** `<mark>`, under `html: 'allow'` */
176
+ export interface Mark {
177
+ type: 'mark';
178
+ children: Inline[];
179
+ }
180
+
181
+ /** What a document may contain: the policy for one use of `md.parse` */
182
+ export interface ParseOptions {
183
+ /**
184
+ * A folder from the project root (`/content/posts/`): relative image and link URLs become root
185
+ * paths under it (`./diagram.png` → `/content/posts/diagram.png`), so the image pipeline finds a
186
+ * file next to the markdown. Links to other `.md` files, `#fragments` and absolute URLs stay as
187
+ * written. Leave it out for markdown from an API.
188
+ */
189
+ base?: string;
190
+ /** `'keep'` (default), or `'strong'`: every heading becomes a paragraph of strong text, so the tree has none */
191
+ headings?: 'keep' | 'strong';
192
+ /** `'keep'` (default), or `'link'`: every image becomes a link to it, its text the alt text */
193
+ images?: 'keep' | 'link';
194
+ /**
195
+ * Raw HTML in the source, which is never markup: `'text'` (default) shows it as written, `'drop'`
196
+ * removes it, `'allow'` keeps `<kbd>`, `<sub>`, `<sup>`, `<mark>` and `<details>` with `<summary>`
197
+ * (only `open` of their attributes) and shows the rest as written.
198
+ */
199
+ html?: 'drop' | 'text' | 'allow';
200
+ }
201
+
202
+ /** one entry of `md.headings`: a table of contents */
203
+ export interface TocEntry {
204
+ depth: 1 | 2 | 3 | 4 | 5 | 6;
205
+ /** the heading's anchor, as `md-doc` writes it: `md-` + its slug */
206
+ id: string;
207
+ /** its plain text */
208
+ text: string;
209
+ }
package/sinter/tree.ts ADDED
@@ -0,0 +1,61 @@
1
+ // Helpers that read a parsed tree: `md.headings` (a table of contents) and `md.text` (a description, a
2
+ // reading time). This module does not import the parser, so these stay ordinary helpers when an app
3
+ // makes the parser lazy (`sinter({ lazy })`): they render early and fold at build time on their own.
4
+ // Pure functions of their arguments, with no globals beyond the language's.
5
+ import type { Block, Inline, MdNode, Root, TocEntry } from './sinter.types.js';
6
+
7
+ /** The headings of `doc`, at any depth, in order: `{ depth, id, text }`, the ids the anchors have. */
8
+ export function headings(doc: Root | null | undefined): TocEntry[] {
9
+ const out: TocEntry[] = [];
10
+ const walk = (nodes: readonly Block[]) => {
11
+ for (const n of nodes) {
12
+ if (n.type === 'heading') out.push({ depth: n.depth, id: 'md-' + n.slug, text: text(n) });
13
+ else if (n.type === 'blockquote' || n.type === 'details') walk(n.children);
14
+ else if (n.type === 'list') for (const i of n.children) walk(i.children);
15
+ }
16
+ };
17
+ if (doc) walk(doc.children);
18
+ return out;
19
+ }
20
+
21
+ /**
22
+ * The plain text of a node, a list of nodes or a document: inline content run together (an image
23
+ * gives its alt text, a break a space), blocks separated by a blank line. `''` for nothing.
24
+ */
25
+ export function text(node: MdNode | readonly MdNode[] | null | undefined): string {
26
+ if (node == null) return '';
27
+ if (Array.isArray(node)) return joinOf(node as readonly MdNode[]);
28
+ const n = node as MdNode;
29
+ switch (n.type) {
30
+ case 'text': case 'inlineCode': case 'code': return n.value;
31
+ case 'image': return n.alt;
32
+ case 'break': return ' ';
33
+ case 'thematicBreak': return '';
34
+ case 'details': return [inline(n.summary), joinOf(n.children)].filter(Boolean).join('\n\n');
35
+ case 'tableRow': return n.children.map(text).join('\t');
36
+ case 'table': case 'list': case 'listItem': case 'blockquote': case 'root': return joinOf(n.children);
37
+ default: return inline(n.children);
38
+ }
39
+ }
40
+
41
+ const inline = (nodes: readonly Inline[]) => nodes.map(text).join('');
42
+ function joinOf(nodes: readonly MdNode[]): string {
43
+ // phrasing content runs together; blocks (and rows, items) are separated
44
+ if (nodes.every((n) => INLINE.has(n.type))) return nodes.map(text).join('');
45
+ const sep = nodes[0]?.type === 'tableRow' ? '\n' : '\n\n';
46
+ return nodes.map(text).filter(Boolean).join(sep);
47
+ }
48
+ const INLINE = new Set(['text', 'emphasis', 'strong', 'delete', 'inlineCode', 'break', 'link', 'image', 'kbd', 'sub', 'sup', 'mark']);
49
+
50
+ /**
51
+ * The anchor for a heading's text, as GitHub writes it: lower case, punctuation removed, spaces as
52
+ * `-` (`Getting started!` → `getting-started`). `taken` holds the ids used so far in the document; a
53
+ * repeated one gets `-1`, `-2`, ….
54
+ */
55
+ export function slug(value: string, taken: Set<string>): string {
56
+ const base = value.toLowerCase().trim().replace(/[^\p{L}\p{M}\p{N}\p{Pc} -]/gu, '').replace(/ /g, '-') || 'section';
57
+ let id = base;
58
+ for (let i = 1; taken.has(id); i++) id = `${base}-${i}`;
59
+ taken.add(id);
60
+ return id;
61
+ }