@tiavision/sinter-mail 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +137 -2
- package/docs/mail.md +267 -0
- package/docs/proposals/progressive-rendering.md +180 -0
- package/docs/proposals/sinter-mail.md +520 -0
- package/llms.txt +20 -0
- package/package.json +65 -4
- package/sinter/autolink.ts +98 -0
- package/sinter/components/internal/mail-a.html +5 -0
- package/sinter/components/internal/mail-abbr.html +5 -0
- package/sinter/components/internal/mail-address.html +5 -0
- package/sinter/components/internal/mail-article.html +5 -0
- package/sinter/components/internal/mail-aside.html +5 -0
- package/sinter/components/internal/mail-b.html +5 -0
- package/sinter/components/internal/mail-bdi.html +5 -0
- package/sinter/components/internal/mail-bdo.html +5 -0
- package/sinter/components/internal/mail-blockquote.html +5 -0
- package/sinter/components/internal/mail-br.html +5 -0
- package/sinter/components/internal/mail-center.html +5 -0
- package/sinter/components/internal/mail-cite.html +5 -0
- package/sinter/components/internal/mail-code.html +5 -0
- package/sinter/components/internal/mail-dd.html +5 -0
- package/sinter/components/internal/mail-del.html +5 -0
- package/sinter/components/internal/mail-details.html +5 -0
- package/sinter/components/internal/mail-dfn.html +5 -0
- package/sinter/components/internal/mail-div.html +5 -0
- package/sinter/components/internal/mail-dl.html +5 -0
- package/sinter/components/internal/mail-dt.html +5 -0
- package/sinter/components/internal/mail-em.html +5 -0
- package/sinter/components/internal/mail-figcaption.html +5 -0
- package/sinter/components/internal/mail-figure.html +5 -0
- package/sinter/components/internal/mail-font.html +5 -0
- package/sinter/components/internal/mail-footer.html +5 -0
- package/sinter/components/internal/mail-h1.html +5 -0
- package/sinter/components/internal/mail-h2.html +5 -0
- package/sinter/components/internal/mail-h3.html +5 -0
- package/sinter/components/internal/mail-h4.html +5 -0
- package/sinter/components/internal/mail-h5.html +5 -0
- package/sinter/components/internal/mail-h6.html +5 -0
- package/sinter/components/internal/mail-header.html +5 -0
- package/sinter/components/internal/mail-hr.html +5 -0
- package/sinter/components/internal/mail-i.html +5 -0
- package/sinter/components/internal/mail-img.html +5 -0
- package/sinter/components/internal/mail-ins.html +5 -0
- package/sinter/components/internal/mail-kbd.html +5 -0
- package/sinter/components/internal/mail-li.html +5 -0
- package/sinter/components/internal/mail-main.html +5 -0
- package/sinter/components/internal/mail-mark.html +5 -0
- package/sinter/components/internal/mail-nav.html +5 -0
- package/sinter/components/internal/mail-node.html +5 -0
- package/sinter/components/internal/mail-ol.html +5 -0
- package/sinter/components/internal/mail-orphan.html +5 -0
- package/sinter/components/internal/mail-p.html +5 -0
- package/sinter/components/internal/mail-pre.html +5 -0
- package/sinter/components/internal/mail-q.html +5 -0
- package/sinter/components/internal/mail-s.html +5 -0
- package/sinter/components/internal/mail-samp.html +5 -0
- package/sinter/components/internal/mail-section.html +5 -0
- package/sinter/components/internal/mail-small.html +5 -0
- package/sinter/components/internal/mail-span.html +5 -0
- package/sinter/components/internal/mail-steps.html +5 -0
- package/sinter/components/internal/mail-steps.ts +46 -0
- package/sinter/components/internal/mail-strike.html +5 -0
- package/sinter/components/internal/mail-strong.html +5 -0
- package/sinter/components/internal/mail-sub.html +5 -0
- package/sinter/components/internal/mail-summary.html +5 -0
- package/sinter/components/internal/mail-sup.html +5 -0
- package/sinter/components/internal/mail-table.html +5 -0
- package/sinter/components/internal/mail-time.html +5 -0
- package/sinter/components/internal/mail-tt.html +5 -0
- package/sinter/components/internal/mail-u.html +5 -0
- package/sinter/components/internal/mail-ul.html +5 -0
- package/sinter/components/internal/mail-var.html +5 -0
- package/sinter/components/internal/mail-wbr.html +5 -0
- package/sinter/components/mail-body.html +21 -0
- package/sinter/css/hints.ts +259 -0
- package/sinter/css/index.ts +270 -0
- package/sinter/css/media.ts +251 -0
- package/sinter/css/parse.ts +124 -0
- package/sinter/css/selectors.ts +530 -0
- package/sinter/css/tokenize.ts +279 -0
- package/sinter/css/values.ts +647 -0
- package/sinter/engine.ts +6 -0
- package/sinter/index.ts +5 -0
- package/sinter/parse.ts +355 -0
- package/sinter/parser/entities.ts +22 -0
- package/sinter/parser/index.ts +54 -0
- package/sinter/parser/tokenizer.ts +275 -0
- package/sinter/parser/tree.ts +1265 -0
- package/sinter/plain.ts +125 -0
- package/sinter/raw.ts +28 -0
- package/sinter/sinter.helpers.ts +11 -0
- package/sinter/sinter.types.ts +135 -0
- package/sinter/tags.ts +169 -0
- package/sinter/tree.ts +168 -0
package/sinter/plain.ts
ADDED
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
// `mail.plain(text, options)`: a plain-text body to the tree of sinter.types.ts, the one mail.parse returns for
|
|
2
|
+
// HTML, so <mail-body> renders both. Paragraphs keep their lines and spacing (`white-space: pre-wrap`), `>` quotes
|
|
3
|
+
// become nested blockquotes, the signature after `-- ` a div, and URLs and emails links (autolink.ts, GFM's rules).
|
|
4
|
+
//
|
|
5
|
+
// This module imports no parser (nothing from sinter/parser or parse.ts), so mail.plain stays an ordinary helper
|
|
6
|
+
// when an app makes the package lazy: it renders early and folds at build time. Pure, with no globals beyond the
|
|
7
|
+
// language's, and linear in the text. As md.parse does, it keeps its trees with sinter's memo(): one tree per text
|
|
8
|
+
// and options, frozen and shared.
|
|
9
|
+
import { memo } from '@tiaforge-ui/sinter/memo';
|
|
10
|
+
import { autolink } from './autolink.js';
|
|
11
|
+
import type { Body, Element, Node, PlainOptions } from './sinter.types.js';
|
|
12
|
+
|
|
13
|
+
/** quote levels past this are read as this one, so a run of `>` cannot nest the tree without bound */
|
|
14
|
+
const MAX_DEPTH = 32;
|
|
15
|
+
|
|
16
|
+
/** links made in one body: a real one has a handful; past this, a hostile text's URLs and addresses stay text, so
|
|
17
|
+
* the tree (an element per link) stays small */
|
|
18
|
+
const MAX_LINKS = 2_000;
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* The tree of a plain-text body under `options` (`flowed`, `delsp`: the message's `Content-Type` parameters).
|
|
22
|
+
* The same text and options give the same tree, frozen: change a copy.
|
|
23
|
+
*/
|
|
24
|
+
export function plain(text: string | null | undefined, options?: PlainOptions): Body {
|
|
25
|
+
const o = options ?? {};
|
|
26
|
+
// the options normalized to primitives, so equal options share one tree (delsp means nothing without flowed)
|
|
27
|
+
const flowed = flag(o.flowed, 'flowed'), delsp = flowed && flag(o.delsp, 'delsp');
|
|
28
|
+
return plainTree(typeof text === 'string' ? text : '', flowed, delsp);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function flag(v: unknown, name: string): boolean {
|
|
32
|
+
if (v == null) return false;
|
|
33
|
+
if (typeof v !== 'boolean') throw new TypeError(`mail.plain: \`${name}\` is true or false, not ${JSON.stringify(v)}`);
|
|
34
|
+
return v;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** the conversion itself, kept by its arguments (the least recently used trees go first, past 8 MiB) */
|
|
38
|
+
const plainTree = memo((text: string, flowed: boolean, delsp: boolean): Body => ({
|
|
39
|
+
type: 'body', style: {}, children: blocks(lines(text, flowed, delsp)), images: { origins: [] },
|
|
40
|
+
}), { maxSize: 8 * 1024 * 1024 });
|
|
41
|
+
|
|
42
|
+
/** a logical line: its quote depth, its text without the quote marks, and whether the signature starts at it */
|
|
43
|
+
interface Line { depth: number; text: string; signature: boolean }
|
|
44
|
+
|
|
45
|
+
const blank = (s: string) => !/\S/.test(s);
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* The text's lines, their quote marks read. Without `flowed`, a mark is `>` and an optional space (`> >` is two
|
|
49
|
+
* levels). With `flowed` (RFC 3676), the depth is the count of `>` with no space between, then a space-stuffed
|
|
50
|
+
* line loses its leading space, and a line ending in a space (a soft break) is joined with the next one of the
|
|
51
|
+
* same depth: not across a blank line, which ends a paragraph, nor into or out of the signature separator.
|
|
52
|
+
*/
|
|
53
|
+
function lines(text: string, flowed: boolean, delsp: boolean): Line[] {
|
|
54
|
+
const out: Line[] = [];
|
|
55
|
+
let signed = false, soft = false;
|
|
56
|
+
// the line being joined, in pieces (a long flowed paragraph is not built by repeated concatenation)
|
|
57
|
+
let parts: string[] = [], last: Line | null = null;
|
|
58
|
+
const end = () => { if (last) { last.text = parts.join(''); out.push(last); last = null; parts = []; } };
|
|
59
|
+
for (const raw of text.replace(/\r\n?/g, '\n').split('\n')) {
|
|
60
|
+
let i = 0, depth = 0;
|
|
61
|
+
if (flowed) { while (raw.charCodeAt(i) === 62) i++; depth = i; if (raw[i] === ' ') i++; }
|
|
62
|
+
else while (raw[i] === '>') { i++; depth++; if (raw[i] === ' ') i++; }
|
|
63
|
+
depth = Math.min(depth, MAX_DEPTH);
|
|
64
|
+
const content = i ? raw.slice(i) : raw;
|
|
65
|
+
// the separator is exactly `-- ` (RFC 3676, 4.3; Usenet's convention), unquoted, and only the first one
|
|
66
|
+
const signature = !signed && raw === '-- ';
|
|
67
|
+
if (signature) signed = true;
|
|
68
|
+
if (soft && last && last.depth === depth && !signature && content !== '-- ' && !blank(content)) {
|
|
69
|
+
if (delsp) parts[parts.length - 1] = parts[parts.length - 1]!.slice(0, -1);
|
|
70
|
+
} else {
|
|
71
|
+
end();
|
|
72
|
+
last = { depth, text: '', signature };
|
|
73
|
+
}
|
|
74
|
+
parts.push(content);
|
|
75
|
+
soft = flowed && content.endsWith(' ') && content !== '-- ';
|
|
76
|
+
}
|
|
77
|
+
end();
|
|
78
|
+
return out;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
const element = (tag: Element['tag'], children: Node[], more?: Partial<Element>): Element =>
|
|
82
|
+
({ type: 'element', tag, attrs: {}, style: {}, children, ...more });
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* The blocks of the lines: paragraphs between blank lines, a blockquote per quote level (a change of level ends
|
|
86
|
+
* the paragraph and closes or opens quotes; a blank line only closes them, so no quote is empty), and from the
|
|
87
|
+
* signature on, a signature div holding the rest, its separator the first line of its first paragraph.
|
|
88
|
+
*/
|
|
89
|
+
function blocks(input: readonly Line[]): Node[] {
|
|
90
|
+
const root: Node[] = [];
|
|
91
|
+
// the children of the quotes open at each depth; [0] is the root's, or the signature's once it starts
|
|
92
|
+
const stack: Node[][] = [root];
|
|
93
|
+
let para: string[] = [];
|
|
94
|
+
let links = MAX_LINKS;
|
|
95
|
+
const flush = () => {
|
|
96
|
+
if (!para.length) return;
|
|
97
|
+
const pieces = autolink(para.join('\n'), links);
|
|
98
|
+
for (const p of pieces) if (typeof p !== 'string') links--;
|
|
99
|
+
const children: Node[] = pieces.map((p) =>
|
|
100
|
+
typeof p === 'string' ? { type: 'text', value: p } : element('a', [{ type: 'text', value: p.text }], { attrs: { href: p.href } }));
|
|
101
|
+
stack[stack.length - 1]!.push(element('p', children, { style: { 'white-space': 'pre-wrap' } }));
|
|
102
|
+
para = [];
|
|
103
|
+
};
|
|
104
|
+
const close = (depth: number) => { while (stack.length - 1 > depth) stack.pop(); };
|
|
105
|
+
for (const line of input) {
|
|
106
|
+
if (line.signature) {
|
|
107
|
+
flush();
|
|
108
|
+
close(0);
|
|
109
|
+
const div = element('div', [], { part: 'signature' });
|
|
110
|
+
stack[0]!.push(div);
|
|
111
|
+
stack[0] = div.children;
|
|
112
|
+
}
|
|
113
|
+
if (line.depth !== stack.length - 1) flush();
|
|
114
|
+
if (blank(line.text)) { flush(); close(line.depth); continue; }
|
|
115
|
+
close(line.depth);
|
|
116
|
+
while (stack.length - 1 < line.depth) {
|
|
117
|
+
const quote = element('blockquote', [], { part: 'quote' });
|
|
118
|
+
stack[stack.length - 1]!.push(quote);
|
|
119
|
+
stack.push(quote.children);
|
|
120
|
+
}
|
|
121
|
+
para.push(line.text);
|
|
122
|
+
}
|
|
123
|
+
flush();
|
|
124
|
+
return root;
|
|
125
|
+
}
|
package/sinter/raw.ts
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
// The raw tree: what the HTML parser (sinter/parser) builds and the cascade (sinter/css) reads, before
|
|
2
|
+
// parse.ts keeps only what an email may contain. It is the document the browser would build from the same
|
|
3
|
+
// HTML: every element, with its attributes as written (names lowercase), and its text. Comments, doctypes
|
|
4
|
+
// and processing instructions are not in it; neither is foreign content (`<svg>`, `<math>`), which is
|
|
5
|
+
// dropped with its subtree. `<style>` elements are in the tree with their text as one Text child.
|
|
6
|
+
|
|
7
|
+
export interface RawText {
|
|
8
|
+
type: 'text';
|
|
9
|
+
value: string;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
export interface RawElement {
|
|
13
|
+
type: 'element';
|
|
14
|
+
/** lowercase, as the browser's `localName` */
|
|
15
|
+
tag: string;
|
|
16
|
+
/** in source order, names lowercase, the first of duplicate names kept (as the browser does) */
|
|
17
|
+
attrs: [name: string, value: string][];
|
|
18
|
+
children: RawNode[];
|
|
19
|
+
parent: RawElement | null;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export type RawNode = RawElement | RawText;
|
|
23
|
+
|
|
24
|
+
/** an attribute's value, or null */
|
|
25
|
+
export function attr(el: RawElement, name: string): string | null {
|
|
26
|
+
for (const [n, v] of el.attrs) if (n === name) return v;
|
|
27
|
+
return null;
|
|
28
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
// The library's helpers, in three modules under one namespace. An app re-exports the package as a
|
|
2
|
+
// namespace (`export * as mail from '@tiavision/sinter-mail'` in its src/sinter.helpers.ts) and calls
|
|
3
|
+
// `mail.parse`, `mail.plain`, `mail.text` and `mail.links` in markup.
|
|
4
|
+
//
|
|
5
|
+
// - parse.ts imports the parser (`@tiavision/sinter-mail/parser`). An app that lists this package in
|
|
6
|
+
// `sinter({ lazy })` makes it load when a let first needs it; the let waits for it.
|
|
7
|
+
// - plain.ts and tree.ts import no parser, so `mail.plain`, `mail.text` and `mail.links` stay ordinary
|
|
8
|
+
// helpers either way: they render early and fold at build time.
|
|
9
|
+
export { parse } from './parse.js';
|
|
10
|
+
export { plain } from './plain.js';
|
|
11
|
+
export { text, links, progressive } from './tree.js';
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
// The tree that mail.parse (HTML) and mail.plain (plain text) return, and that <mail-body> renders. An app
|
|
2
|
+
// names these in its own declarations (`export type { Body } from '@tiavision/sinter-mail'` in its
|
|
3
|
+
// src/sinter.types.ts); an API that runs the parse on the server sends this tree as JSON.
|
|
4
|
+
//
|
|
5
|
+
// Every element is one the browser's own parser would build from the same HTML, restricted to the tags
|
|
6
|
+
// of sinter/tags.ts, with only that tag's attributes and the properties the cascade resolved for it.
|
|
7
|
+
|
|
8
|
+
/** The allowed tags (sinter/tags.ts is the table; test/components.test.ts checks that the two agree). */
|
|
9
|
+
export type Tag =
|
|
10
|
+
| 'a' | 'abbr' | 'address' | 'article' | 'aside' | 'b' | 'bdi' | 'bdo' | 'blockquote' | 'br' | 'caption'
|
|
11
|
+
| 'center' | 'cite' | 'code' | 'col' | 'colgroup' | 'dd' | 'del' | 'details' | 'dfn' | 'div' | 'dl' | 'dt'
|
|
12
|
+
| 'em' | 'figcaption' | 'figure' | 'font' | 'footer' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'header'
|
|
13
|
+
| 'hr' | 'i' | 'img' | 'ins' | 'kbd' | 'li' | 'main' | 'mark' | 'nav' | 'ol' | 'p' | 'pre' | 'q' | 's'
|
|
14
|
+
| 'samp' | 'section' | 'small' | 'span' | 'strike' | 'strong' | 'sub' | 'summary' | 'sup' | 'table'
|
|
15
|
+
| 'tbody' | 'td' | 'tfoot' | 'th' | 'thead' | 'time' | 'tr' | 'tt' | 'u' | 'ul' | 'var' | 'wbr';
|
|
16
|
+
|
|
17
|
+
/** The attributes an element may keep (which ones a tag keeps: sinter/tags.ts). Values are strings. */
|
|
18
|
+
export interface Attrs {
|
|
19
|
+
href?: string;
|
|
20
|
+
title?: string;
|
|
21
|
+
src?: string;
|
|
22
|
+
alt?: string;
|
|
23
|
+
width?: string;
|
|
24
|
+
height?: string;
|
|
25
|
+
id?: string;
|
|
26
|
+
dir?: string;
|
|
27
|
+
lang?: string;
|
|
28
|
+
colspan?: string;
|
|
29
|
+
rowspan?: string;
|
|
30
|
+
headers?: string;
|
|
31
|
+
scope?: string;
|
|
32
|
+
abbr?: string;
|
|
33
|
+
span?: string;
|
|
34
|
+
start?: string;
|
|
35
|
+
reversed?: string;
|
|
36
|
+
type?: string;
|
|
37
|
+
value?: string;
|
|
38
|
+
open?: string;
|
|
39
|
+
cite?: string;
|
|
40
|
+
datetime?: string;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* The declarations the cascade resolved for an element: its legacy attributes, the email's `<style>`
|
|
45
|
+
* rules and its `style` attribute, in that order of precedence, then only the allowed properties
|
|
46
|
+
* (sinter/tags.ts, PROPERTIES), each value re-serialized. Rendered inline with `data-sn-style`.
|
|
47
|
+
*/
|
|
48
|
+
export type Style = { [P in Property]?: string };
|
|
49
|
+
|
|
50
|
+
export type Property =
|
|
51
|
+
| 'color' | 'background-color'
|
|
52
|
+
| 'font-family' | 'font-size' | 'font-style' | 'font-weight' | 'font-variant'
|
|
53
|
+
| 'line-height' | 'letter-spacing' | 'word-spacing'
|
|
54
|
+
| 'text-align' | 'text-decoration' | 'text-transform' | 'text-indent' | 'white-space'
|
|
55
|
+
| 'vertical-align' | 'word-break' | 'overflow-wrap'
|
|
56
|
+
| 'width' | 'height' | 'min-width' | 'max-width' | 'min-height' | 'max-height'
|
|
57
|
+
| 'margin-top' | 'margin-right' | 'margin-bottom' | 'margin-left'
|
|
58
|
+
| 'padding-top' | 'padding-right' | 'padding-bottom' | 'padding-left'
|
|
59
|
+
| 'border-top-width' | 'border-right-width' | 'border-bottom-width' | 'border-left-width'
|
|
60
|
+
| 'border-top-style' | 'border-right-style' | 'border-bottom-style' | 'border-left-style'
|
|
61
|
+
| 'border-top-color' | 'border-right-color' | 'border-bottom-color' | 'border-left-color'
|
|
62
|
+
| 'border-top-left-radius' | 'border-top-right-radius' | 'border-bottom-right-radius' | 'border-bottom-left-radius'
|
|
63
|
+
| 'border-collapse' | 'border-spacing' | 'table-layout' | 'caption-side'
|
|
64
|
+
| 'display' | 'list-style-type' | 'list-style-position' | 'overflow' | 'opacity' | 'box-sizing' | 'float' | 'clear';
|
|
65
|
+
|
|
66
|
+
export interface Text {
|
|
67
|
+
type: 'text';
|
|
68
|
+
value: string;
|
|
69
|
+
/** the node's index in document order, set by mail.progressive: its row's key, and where a step of a progressive render ends */
|
|
70
|
+
n?: number;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export interface Element {
|
|
74
|
+
type: 'element';
|
|
75
|
+
tag: Tag;
|
|
76
|
+
attrs: Attrs;
|
|
77
|
+
style: Style;
|
|
78
|
+
/** what the element is in the message: a quoted reply, the signature (mail.plain sets them) */
|
|
79
|
+
part?: 'quote' | 'signature';
|
|
80
|
+
children: Node[];
|
|
81
|
+
/** the node's index in document order, and the last index in its subtree (mail.progressive) */
|
|
82
|
+
n?: number;
|
|
83
|
+
z?: number;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
export type Node = Element | Text;
|
|
87
|
+
|
|
88
|
+
export interface Body {
|
|
89
|
+
type: 'body';
|
|
90
|
+
/** the resolved style of the email's `<body>` (its background, its font), rendered on the root */
|
|
91
|
+
style: Style;
|
|
92
|
+
children: Node[];
|
|
93
|
+
images: ImageInfo;
|
|
94
|
+
/** set by mail.progressive: <mail-body> renders the nodes with an index below this first, the rest after the browser has painted them */
|
|
95
|
+
head?: number;
|
|
96
|
+
/** set by mail.progressive: the body up to `head`, the subtrees it holds whole shared with the body */
|
|
97
|
+
first?: Body;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
export interface ImageInfo {
|
|
101
|
+
/** every remote image's origin (`https://cdn.example`), sorted, once each, whatever `images` is */
|
|
102
|
+
origins: string[];
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
export interface ParseOptions {
|
|
106
|
+
/**
|
|
107
|
+
* What a remote (`http:`, `https:`) image becomes: `'block'` (the default) leaves it out, keeping its box;
|
|
108
|
+
* `'allow'` keeps it as written; `'proxy'` keeps it through the `proxy` template.
|
|
109
|
+
*/
|
|
110
|
+
images?: 'block' | 'allow' | 'proxy';
|
|
111
|
+
/** with `images: 'proxy'`: a URL template with `{url}` once, `'/api/email/proxy-image?url={url}'` */
|
|
112
|
+
proxy?: string;
|
|
113
|
+
/**
|
|
114
|
+
* `cid:` images (inline parts): a map from content id (without `<>`) to a URL, or a template with
|
|
115
|
+
* `{cid}` once. An unresolved one is left out.
|
|
116
|
+
*/
|
|
117
|
+
cid?: Record<string, string> | string;
|
|
118
|
+
/** the width `@media` rules are evaluated at: `'wide'` (the default, 800 px) or `'narrow'` (375 px) */
|
|
119
|
+
media?: 'wide' | 'narrow';
|
|
120
|
+
/** the largest `data:` image kept, in characters of its URL (default 65536; 0 keeps none) */
|
|
121
|
+
dataImages?: number;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
export interface PlainOptions {
|
|
125
|
+
/** the text is `format=flowed` (RFC 3676): soft line breaks are joined back into paragraphs */
|
|
126
|
+
flowed?: boolean;
|
|
127
|
+
/** with `flowed`: `DelSp=yes`, the space before a soft line break is removed too */
|
|
128
|
+
delsp?: boolean;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/** a link of the body, as mail.links returns it */
|
|
132
|
+
export interface LinkInfo {
|
|
133
|
+
href: string;
|
|
134
|
+
text: string;
|
|
135
|
+
}
|
package/sinter/tags.ts
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
// The tag table: what an email may contain. The single source for parse.ts (what is kept, dropped or
|
|
2
|
+
// renamed), for the tree's `Tag` type (test/components.test.ts checks they agree) and for the generated
|
|
3
|
+
// components (scripts/build-components.mjs writes sinter/components/internal/ from it).
|
|
4
|
+
import type { Attrs, Property, Tag } from './sinter.types.js';
|
|
5
|
+
|
|
6
|
+
type AttrName = keyof Attrs;
|
|
7
|
+
|
|
8
|
+
// ── Properties ────────────────────────────────────────────────────────────────────────────────────────
|
|
9
|
+
// The properties the cascade keeps (sinter/css checks and re-serializes each value). Grouped by where they
|
|
10
|
+
// do something, so each generated component binds only the properties that apply to its element.
|
|
11
|
+
|
|
12
|
+
export const TEXT: readonly Property[] = [
|
|
13
|
+
'color', 'font-family', 'font-size', 'font-style', 'font-weight', 'font-variant', 'line-height',
|
|
14
|
+
'letter-spacing', 'word-spacing', 'text-align', 'text-decoration', 'text-transform', 'text-indent',
|
|
15
|
+
'white-space', 'word-break', 'overflow-wrap',
|
|
16
|
+
];
|
|
17
|
+
export const BOX: readonly Property[] = [
|
|
18
|
+
'background-color', 'display', 'vertical-align', 'width', 'height', 'min-width', 'max-width', 'min-height', 'max-height',
|
|
19
|
+
'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
|
|
20
|
+
'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
|
|
21
|
+
'border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width',
|
|
22
|
+
'border-top-style', 'border-right-style', 'border-bottom-style', 'border-left-style',
|
|
23
|
+
'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color',
|
|
24
|
+
'border-top-left-radius', 'border-top-right-radius', 'border-bottom-right-radius', 'border-bottom-left-radius',
|
|
25
|
+
'overflow', 'opacity', 'box-sizing', 'float', 'clear',
|
|
26
|
+
];
|
|
27
|
+
export const TABLE: readonly Property[] = ['border-collapse', 'border-spacing', 'table-layout', 'caption-side'];
|
|
28
|
+
export const LIST: readonly Property[] = ['list-style-type', 'list-style-position'];
|
|
29
|
+
|
|
30
|
+
/** every property the cascade keeps */
|
|
31
|
+
export const PROPERTIES: readonly Property[] = [...TEXT, ...BOX, ...TABLE, ...LIST];
|
|
32
|
+
|
|
33
|
+
// ── Attributes ────────────────────────────────────────────────────────────────────────────────────────
|
|
34
|
+
// Kept as attributes, literal keys in the components. The legacy presentational attributes (bgcolor,
|
|
35
|
+
// align, valign, border, cellpadding, cellspacing, <font color face size>, width and height but on
|
|
36
|
+
// images) are read by the cascade and become styles; they are not attributes of the tree.
|
|
37
|
+
|
|
38
|
+
const GLOBAL: readonly AttrName[] = ['dir', 'lang', 'title', 'id'];
|
|
39
|
+
|
|
40
|
+
// ── Tags ──────────────────────────────────────────────────────────────────────────────────────────────
|
|
41
|
+
|
|
42
|
+
export interface TagInfo {
|
|
43
|
+
/** attributes beyond GLOBAL */
|
|
44
|
+
attrs: readonly AttrName[];
|
|
45
|
+
/** the properties its component binds */
|
|
46
|
+
props: readonly Property[];
|
|
47
|
+
/** void: no children */
|
|
48
|
+
void?: true;
|
|
49
|
+
/**
|
|
50
|
+
* rendered inside its table's component, never on its own: the HTML parser would move a component's
|
|
51
|
+
* tag written inside a <table> out of it (foster parenting), so a table's structure is one component
|
|
52
|
+
*/
|
|
53
|
+
inTable?: true;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
const FLOW = [...TEXT, ...BOX];
|
|
57
|
+
const t = (attrs: readonly AttrName[] = [], props: readonly Property[] = FLOW, extra: Partial<TagInfo> = {}): TagInfo => ({ attrs, props, ...extra });
|
|
58
|
+
|
|
59
|
+
export const TAGS: Record<Tag, TagInfo> = {
|
|
60
|
+
a: t(['href']),
|
|
61
|
+
abbr: t(),
|
|
62
|
+
address: t(),
|
|
63
|
+
article: t(),
|
|
64
|
+
aside: t(),
|
|
65
|
+
b: t(),
|
|
66
|
+
bdi: t(),
|
|
67
|
+
bdo: t(),
|
|
68
|
+
blockquote: t(['cite']),
|
|
69
|
+
br: t([], ['clear'], { void: true }),
|
|
70
|
+
caption: t([], [...FLOW, ...TABLE], { inTable: true }),
|
|
71
|
+
center: t(),
|
|
72
|
+
cite: t(),
|
|
73
|
+
code: t(),
|
|
74
|
+
col: t(['span'], ['width', 'background-color', 'border-left-width', 'border-right-width', 'border-left-style', 'border-right-style', 'border-left-color', 'border-right-color'], { void: true, inTable: true }),
|
|
75
|
+
colgroup: t(['span'], ['width', 'background-color'], { inTable: true }),
|
|
76
|
+
dd: t(),
|
|
77
|
+
del: t(['cite', 'datetime']),
|
|
78
|
+
details: t(['open']),
|
|
79
|
+
dfn: t(),
|
|
80
|
+
div: t(),
|
|
81
|
+
dl: t(),
|
|
82
|
+
dt: t(),
|
|
83
|
+
em: t(),
|
|
84
|
+
figcaption: t(),
|
|
85
|
+
figure: t(),
|
|
86
|
+
font: t(),
|
|
87
|
+
footer: t(),
|
|
88
|
+
h1: t(), h2: t(), h3: t(), h4: t(), h5: t(), h6: t(),
|
|
89
|
+
header: t(),
|
|
90
|
+
hr: t([], FLOW, { void: true }),
|
|
91
|
+
i: t(),
|
|
92
|
+
img: t(['src', 'alt', 'width', 'height'], BOX, { void: true }),
|
|
93
|
+
ins: t(['cite', 'datetime']),
|
|
94
|
+
kbd: t(),
|
|
95
|
+
li: t(['value'], [...FLOW, ...LIST]),
|
|
96
|
+
main: t(),
|
|
97
|
+
mark: t(),
|
|
98
|
+
nav: t(),
|
|
99
|
+
ol: t(['start', 'reversed', 'type'], [...FLOW, ...LIST]),
|
|
100
|
+
p: t(),
|
|
101
|
+
pre: t(),
|
|
102
|
+
q: t(['cite']),
|
|
103
|
+
s: t(),
|
|
104
|
+
samp: t(),
|
|
105
|
+
section: t(),
|
|
106
|
+
small: t(),
|
|
107
|
+
span: t(),
|
|
108
|
+
strike: t(),
|
|
109
|
+
strong: t(),
|
|
110
|
+
sub: t(),
|
|
111
|
+
summary: t(),
|
|
112
|
+
sup: t(),
|
|
113
|
+
table: t([], [...FLOW, ...TABLE]),
|
|
114
|
+
tbody: t([], FLOW, { inTable: true }),
|
|
115
|
+
td: t(['colspan', 'rowspan', 'headers', 'abbr'], FLOW, { inTable: true }),
|
|
116
|
+
tfoot: t([], FLOW, { inTable: true }),
|
|
117
|
+
th: t(['colspan', 'rowspan', 'headers', 'scope', 'abbr'], FLOW, { inTable: true }),
|
|
118
|
+
thead: t([], FLOW, { inTable: true }),
|
|
119
|
+
time: t(['datetime']),
|
|
120
|
+
tr: t([], FLOW, { inTable: true }),
|
|
121
|
+
tt: t(),
|
|
122
|
+
u: t(),
|
|
123
|
+
ul: t(['type'], [...FLOW, ...LIST]),
|
|
124
|
+
var: t(),
|
|
125
|
+
wbr: t([], [], { void: true }),
|
|
126
|
+
};
|
|
127
|
+
|
|
128
|
+
/** the attributes a tag keeps, GLOBAL included */
|
|
129
|
+
export const attrsOf = (tag: Tag): readonly AttrName[] => [...GLOBAL, ...TAGS[tag].attrs];
|
|
130
|
+
|
|
131
|
+
// ── What is not kept ──────────────────────────────────────────────────────────────────────────────────
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Dropped with everything inside: what runs, embeds, submits or describes the document rather than
|
|
135
|
+
* being its content.
|
|
136
|
+
*/
|
|
137
|
+
export const DROP: ReadonlySet<string> = new Set([
|
|
138
|
+
'script', 'style', 'template', 'noscript', 'noembed', 'noframes', 'iframe', 'frame', 'frameset', 'object',
|
|
139
|
+
'embed', 'applet', 'param', 'video', 'audio', 'source', 'track', 'canvas', 'map', 'area', 'picture',
|
|
140
|
+
'form', 'input', 'button', 'select', 'option', 'optgroup', 'datalist', 'textarea', 'output', 'progress',
|
|
141
|
+
'meter', 'keygen', 'link', 'meta', 'base', 'basefont', 'title', 'head', 'dialog', 'slot', 'portal',
|
|
142
|
+
'marquee', 'blink', 'xmp', 'plaintext', 'listing', 'image', 'math', 'svg',
|
|
143
|
+
]);
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* Kept as another allowed tag, children included: elements the browser renders as that tag would, so the
|
|
147
|
+
* email looks the same. Any other unknown element (`o:p`, `custom-tag`, `label`) is a `span`, as the
|
|
148
|
+
* browser renders an unknown element: inline, with its styles.
|
|
149
|
+
*/
|
|
150
|
+
// `<html>` and `<body>` are not elements of the tree: the body's children are the Body's, and its style
|
|
151
|
+
// is the Body's (parse.ts).
|
|
152
|
+
export const RENAME: Readonly<Record<string, Tag>> = {
|
|
153
|
+
fieldset: 'div',
|
|
154
|
+
legend: 'div',
|
|
155
|
+
hgroup: 'div',
|
|
156
|
+
menu: 'ul',
|
|
157
|
+
dir: 'ul',
|
|
158
|
+
big: 'span',
|
|
159
|
+
nobr: 'span',
|
|
160
|
+
label: 'span',
|
|
161
|
+
data: 'span',
|
|
162
|
+
ruby: 'span',
|
|
163
|
+
rb: 'span',
|
|
164
|
+
rp: 'span',
|
|
165
|
+
rt: 'span',
|
|
166
|
+
rtc: 'span',
|
|
167
|
+
acronym: 'abbr',
|
|
168
|
+
search: 'div',
|
|
169
|
+
};
|
package/sinter/tree.ts
ADDED
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
// Helpers that read a body's tree: `mail.text` (a preview, a search snippet) and `mail.links` (an app that lists
|
|
2
|
+
// or checks a message's links). This module does not import the parser, so these stay ordinary helpers when an
|
|
3
|
+
// app makes the package lazy: they render early and fold at build time. Pure functions of their arguments, with
|
|
4
|
+
// no globals beyond the language's, no cache (a walk is cheap next to a parse), and no recursion: a deep tree
|
|
5
|
+
// does not overflow the stack.
|
|
6
|
+
import type { Body, Element, LinkInfo, Node, Tag } from './sinter.types.js';
|
|
7
|
+
|
|
8
|
+
/** how an element lays out its text: on the line, as a block, a table row or cell, or not at all */
|
|
9
|
+
type Kind = 'inline' | 'block' | 'row' | 'cell' | 'none';
|
|
10
|
+
|
|
11
|
+
const INLINE = new Set<Tag>([
|
|
12
|
+
'a', 'abbr', 'b', 'bdi', 'bdo', 'br', 'cite', 'code', 'del', 'dfn', 'em', 'font', 'i', 'img', 'ins', 'kbd', 'mark',
|
|
13
|
+
'q', 's', 'samp', 'small', 'span', 'strike', 'strong', 'sub', 'sup', 'time', 'tt', 'u', 'var', 'wbr',
|
|
14
|
+
]);
|
|
15
|
+
/** blocks set apart by a blank line, as a reader sees paragraphs (innerText does it for `p`) */
|
|
16
|
+
const PARAGRAPH = new Set<Tag>(['p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'blockquote', 'pre', 'ul', 'ol', 'dl', 'table', 'figure']);
|
|
17
|
+
|
|
18
|
+
/** the element's kind: its resolved `display` first (an email's `display: none` preheader is not shown), then its tag's */
|
|
19
|
+
function kindOf(el: Element): Kind {
|
|
20
|
+
const d = el.style.display;
|
|
21
|
+
if (d) {
|
|
22
|
+
if (d === 'none') return 'none';
|
|
23
|
+
if (d.startsWith('inline') || d === 'contents') return 'inline';
|
|
24
|
+
if (d === 'table-row') return 'row';
|
|
25
|
+
if (d === 'table-cell') return 'cell';
|
|
26
|
+
return 'block';
|
|
27
|
+
}
|
|
28
|
+
if (INLINE.has(el.tag)) return 'inline';
|
|
29
|
+
if (el.tag === 'tr') return 'row';
|
|
30
|
+
if (el.tag === 'td' || el.tag === 'th') return 'cell';
|
|
31
|
+
if (el.tag === 'col' || el.tag === 'colgroup') return 'none';
|
|
32
|
+
return 'block';
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** whitespace as written (`pre`, `pre-wrap`, a plain body's paragraphs), newlines only (`pre-line`), or collapsed */
|
|
36
|
+
type Space = 'pre' | 'line' | 'collapse';
|
|
37
|
+
function spaceOf(el: Element, inherited: Space): Space {
|
|
38
|
+
const w = el.style['white-space'];
|
|
39
|
+
if (w === 'pre' || w === 'pre-wrap' || w === 'break-spaces') return 'pre';
|
|
40
|
+
if (w === 'pre-line') return 'line';
|
|
41
|
+
if (w === 'normal' || w === 'nowrap') return 'collapse';
|
|
42
|
+
return el.tag === 'pre' ? 'pre' : inherited;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* The text of a node or a body, as a reader sees it, roughly as the browser's `innerText` gives it: texts run
|
|
47
|
+
* together, whitespace collapsed outside preformatted text, a newline for each `br` and between blocks, a blank
|
|
48
|
+
* line between paragraphs, quotes and lists, a tab between table cells, nothing for what `display: none` hides.
|
|
49
|
+
* Never more than one blank line in a row, none at the start or the end. A text node gives its value; `''` for
|
|
50
|
+
* nothing.
|
|
51
|
+
*/
|
|
52
|
+
export function text(node: Node | Body | null | undefined): string {
|
|
53
|
+
if (node == null) return '';
|
|
54
|
+
if (node.type === 'text') return node.value;
|
|
55
|
+
let out = '', breaks = 0, space = false, tab = false;
|
|
56
|
+
const put = (s: string) => {
|
|
57
|
+
if (out) {
|
|
58
|
+
if (breaks) out += '\n'.repeat(breaks);
|
|
59
|
+
else if (tab) out += '\t';
|
|
60
|
+
else if (space && !out.endsWith('\n')) out += ' ';
|
|
61
|
+
}
|
|
62
|
+
breaks = 0; space = tab = false;
|
|
63
|
+
out += s;
|
|
64
|
+
};
|
|
65
|
+
const write = (value: string, ws: Space) => {
|
|
66
|
+
if (ws === 'pre') { if (value) put(value); return; }
|
|
67
|
+
// collapsed: each run of whitespace one space (newlines kept with pre-line), none at a line's start
|
|
68
|
+
const re = ws === 'line' ? /[ \t\f\r]*\n[ \t\f\r\n]*|[ \t\f\r]+/g : /[ \t\n\f\r]+/g;
|
|
69
|
+
let pos = 0, m: RegExpExecArray | null;
|
|
70
|
+
while ((m = re.exec(value))) {
|
|
71
|
+
if (m.index > pos) put(value.slice(pos, m.index));
|
|
72
|
+
if (m[0].includes('\n')) put('\n'); else space = true;
|
|
73
|
+
pos = m.index + m[0].length;
|
|
74
|
+
}
|
|
75
|
+
if (pos < value.length) put(value.slice(pos));
|
|
76
|
+
};
|
|
77
|
+
type Frame = { nodes: readonly Node[]; i: number; ws: Space; after: number; cells: number };
|
|
78
|
+
const root = node.type === 'element' ? node : null;
|
|
79
|
+
const stack: Frame[] = [{ nodes: node.children, i: 0, ws: root ? spaceOf(root, 'collapse') : 'collapse', after: 0, cells: 0 }];
|
|
80
|
+
while (stack.length) {
|
|
81
|
+
const f = stack[stack.length - 1]!;
|
|
82
|
+
if (f.i >= f.nodes.length) {
|
|
83
|
+
stack.pop();
|
|
84
|
+
if (f.after) { breaks = Math.max(breaks, f.after); space = tab = false; }
|
|
85
|
+
continue;
|
|
86
|
+
}
|
|
87
|
+
const n = f.nodes[f.i++]!;
|
|
88
|
+
if (n.type === 'text') { write(n.value, f.ws); continue; }
|
|
89
|
+
if (n.tag === 'br') {
|
|
90
|
+
// a line break of its own, after the breaks already due
|
|
91
|
+
if (out && breaks) out += '\n'.repeat(breaks);
|
|
92
|
+
breaks = 0; space = tab = false;
|
|
93
|
+
out += '\n';
|
|
94
|
+
continue;
|
|
95
|
+
}
|
|
96
|
+
const kind = kindOf(n);
|
|
97
|
+
if (kind === 'none') continue;
|
|
98
|
+
let after = 0;
|
|
99
|
+
if (kind === 'block') after = PARAGRAPH.has(n.tag) ? 2 : 1;
|
|
100
|
+
else if (kind === 'row') after = 1;
|
|
101
|
+
else if (kind === 'cell' && f.cells++ && !breaks) { tab = true; space = false; }
|
|
102
|
+
if (after) { breaks = Math.max(breaks, after); space = tab = false; }
|
|
103
|
+
stack.push({ nodes: n.children, i: 0, ws: spaceOf(n, f.ws), after, cells: 0 });
|
|
104
|
+
}
|
|
105
|
+
return out.replace(/\n{3,}/g, '\n\n').replace(/^\n+|\n+$/g, '');
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** Every link of `body` (an `a` with an `href`), in document order: its href and its text (`text()`). */
|
|
109
|
+
export function links(body: Body | null | undefined): LinkInfo[] {
|
|
110
|
+
const out: LinkInfo[] = [];
|
|
111
|
+
if (!body) return out;
|
|
112
|
+
const stack: Array<{ nodes: readonly Node[]; i: number }> = [{ nodes: body.children, i: 0 }];
|
|
113
|
+
while (stack.length) {
|
|
114
|
+
const f = stack[stack.length - 1]!;
|
|
115
|
+
if (f.i >= f.nodes.length) { stack.pop(); continue; }
|
|
116
|
+
const n = f.nodes[f.i++]!;
|
|
117
|
+
if (n.type !== 'element') continue;
|
|
118
|
+
if (n.tag === 'a' && n.attrs.href) out.push({ href: n.attrs.href, text: text(n) });
|
|
119
|
+
if (n.children.length) stack.push({ nodes: n.children, i: 0 });
|
|
120
|
+
}
|
|
121
|
+
return out;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Numbers the nodes of `body` in document order (`n`; `z` on an element: the last number in its subtree), sets
|
|
126
|
+
* `body.head` and `body.first` (the body up to `head`), and returns it: <mail-body> then renders the first `head`
|
|
127
|
+
* nodes in the task that receives the body and the rest in steps, a task each, after the browser has painted them.
|
|
128
|
+
* In place, without recursion. A body that is not numbered renders whole in one task (a `file:` email, folded at
|
|
129
|
+
* build time, stays whole and ships no JavaScript).
|
|
130
|
+
*/
|
|
131
|
+
export function progressive(body: Body, head = 200): Body {
|
|
132
|
+
let i = 0;
|
|
133
|
+
const stack: Array<[Element, number]> = [];
|
|
134
|
+
const visit = (list: Node[]) => { for (let k = list.length; k--;) stack.push([list[k] as Element, 0]); };
|
|
135
|
+
visit(body.children);
|
|
136
|
+
while (stack.length) {
|
|
137
|
+
const top = stack[stack.length - 1]!;
|
|
138
|
+
const [n, state] = top;
|
|
139
|
+
if (state === 0) {
|
|
140
|
+
n.n = i++;
|
|
141
|
+
if (n.type !== 'element') { stack.pop(); continue; }
|
|
142
|
+
top[1] = 1;
|
|
143
|
+
visit(n.children);
|
|
144
|
+
} else { n.z = i - 1; stack.pop(); }
|
|
145
|
+
}
|
|
146
|
+
body.head = head;
|
|
147
|
+
body.first = upTo(body, head);
|
|
148
|
+
return body;
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* A numbered `body` up to node `upto`, for a step of a progressive render: the nodes below it, an element whose
|
|
153
|
+
* subtree is all below it as it is (the same object), one that `upto` cuts copied with its children up to it. Rows
|
|
154
|
+
* are keyed by the nodes' numbers, so a copy keeps its row and only the copied elements render again.
|
|
155
|
+
*/
|
|
156
|
+
export function upTo(body: Body, upto: number): Body {
|
|
157
|
+
const cut = (list: Node[]): Node[] => {
|
|
158
|
+
const out: Node[] = [];
|
|
159
|
+
for (const c of list) {
|
|
160
|
+
if (c.n! >= upto) break;
|
|
161
|
+
if (c.type !== 'element' || c.z! < upto) out.push(c);
|
|
162
|
+
else out.push({ ...c, children: cut(c.children) });
|
|
163
|
+
}
|
|
164
|
+
return out;
|
|
165
|
+
};
|
|
166
|
+
const { first: _, ...rest } = body;
|
|
167
|
+
return { ...rest, children: cut(body.children) };
|
|
168
|
+
}
|