@h-k-dev/dawn 0.0.0-stage → 1.0.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/README.md CHANGED
@@ -1,3 +1,46 @@
1
- # Temporary Holding Version
1
+ # @h-k-dev/dawn
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Dawn is the email render engine of [@h-k-dev/angular-email-editor](https://www.npmjs.com/package/@h-k-dev/angular-email-editor): an email drawn as a mail client draws it, light and dark. It has no framework in it and no dependencies. It runs in a browser, or on a server with a DOM.
4
+
5
+ Dark mode is rendering, never declaring. An email carries its light colours only. In dark, Dawn draws every colour the way a WebKit-based client draws an email that declares no dark mode: lightness inverted, hue kept, pictures untouched, on a dark surface. An email that does declare dark mode keeps its own rules. The editor uses the same engine for its dark paper, its swatches, its reader and its thumbnails, so they never disagree.
6
+
7
+ ## Install
8
+
9
+ ```sh
10
+ npm install @h-k-dev/dawn
11
+ ```
12
+
13
+ The editor depends on it already: an app using the editor imports Dawn from `@h-k-dev/angular-email-editor` too.
14
+
15
+ ## Draw an email
16
+
17
+ ```ts
18
+ import { renderDawn } from '@h-k-dev/dawn';
19
+
20
+ // A fragment (a message body) or a whole document, drawn as a document for
21
+ // a sandboxed frame.
22
+ const html = renderDawn(body, { scheme: 'dark', pane: 'phone' });
23
+ ```
24
+
25
+ ## On a server
26
+
27
+ Dawn reads HTML with the DOM (`DOMParser`, `<template>`). Give it one, for example with [linkedom](https://www.npmjs.com/package/linkedom), [happy-dom](https://www.npmjs.com/package/happy-dom) or [jsdom](https://www.npmjs.com/package/jsdom), set as the globals:
28
+
29
+ ```ts
30
+ import { JSDOM } from 'jsdom';
31
+ const { window } = new JSDOM('');
32
+ Object.assign(globalThis, { window, document: window.document, DOMParser: window.DOMParser });
33
+
34
+ const { renderDawn } = await import('@h-k-dev/dawn');
35
+ const thumbnail = renderDawn(body, { scheme: 'dark' });
36
+ ```
37
+
38
+ ## What is in it
39
+
40
+ - `renderDawn(html, { scheme, pane? })`: an email as Dawn draws it, light or dark.
41
+ - `dawnDarkColor(token)`: one CSS colour as Dawn draws it dark, for example to show a swatch on a dark page.
42
+ - `dawnDarkDeclarations`, `dawnDarkStyleSheet`, `dawnDarkDocument`: the dark drawing applied to a style attribute, a style sheet or a whole document. `declaresDark(doc)` tells whether an email declares its own dark mode.
43
+ - `renderForClient(html, client, { dark?, pane? })`: what Gmail, classic Outlook and an Apple client keep of an email, drawn for a frame. `CSS_SUPPORT` and `findCssIssues` hold the client-support data it reads.
44
+ - `sentBody(html)`: a fragment as the editor sends it, with images fitted and stacking columns marked.
45
+
46
+ The colour transform follows WebKit's invert-lightness filter, used under WebKit's BSD licence (Copyright © Apple Inc.). Dawn is not made, approved or endorsed by Apple.