@superdoc/fonts 0.5.0 → 0.6.0-next.9

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 (2) hide show
  1. package/README.md +98 -5
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,11 +1,21 @@
1
1
  # @superdoc/fonts
2
2
 
3
- Optional font substitutes for SuperDoc, including Carlito for Calibri, Caladea for Cambria, and Liberation Serif for Times New Roman. The package contains WOFF2 assets and their license texts.
3
+ Optional font substitutes for the [`superdoc`](https://www.npmjs.com/package/superdoc)
4
+ DOCX editor. Documents that use Word fonts your users may not have, such as
5
+ Calibri, Cambria, or Times New Roman, lay out closer to Word with
6
+ metric-compatible substitutes like Carlito, Caladea, and Liberation Serif. The
7
+ package contains WOFF2 assets and their license texts.
8
+
9
+ [Documentation](https://docs.superdoc.dev/editor/fonts) · [GitHub](https://github.com/superdoc/docx-editor)
10
+
11
+ ## Install
4
12
 
5
13
  ```sh
6
14
  npm install superdoc @superdoc/fonts
7
15
  ```
8
16
 
17
+ ## Quick start
18
+
9
19
  ```js
10
20
  import { SuperDoc } from 'superdoc';
11
21
  import 'superdoc/style.css';
@@ -18,11 +28,60 @@ const superdoc = new SuperDoc({
18
28
  });
19
29
  ```
20
30
 
21
- Create an element with `id="editor"` and serve your document at `/sample.docx`. Your bundler resolves the package's font URLs; no manual font copy step is needed. SuperDoc loads the faces needed by the document. Allow their served origin in your Content Security Policy and configure CORS when serving them from another origin.
31
+ With React, pass the same value as a prop:
32
+ `<SuperDocEditor document="/sample.docx" fonts={superdocFonts} />`.
33
+
34
+ Your bundler resolves the package's font URLs; no manual copy step is needed.
35
+ SuperDoc loads only the faces the document uses. Allow their served origin in
36
+ your Content Security Policy, and configure CORS when you serve them from
37
+ another origin.
38
+
39
+ ## Common tasks
40
+
41
+ ### Load only some substitutes
42
+
43
+ Use Word family names. An unknown name throws instead of being ignored.
44
+
45
+ ```js
46
+ import { createSuperDocFonts } from '@superdoc/fonts';
47
+
48
+ const fonts = createSuperDocFonts({ include: ['Calibri', 'Cambria'] });
49
+ // or: createSuperDocFonts({ exclude: ['Cooper Black', 'Brush Script MT'] })
50
+ ```
51
+
52
+ `BUNDLED_FAMILY_NAMES` lists every family the pack covers.
53
+
54
+ ### Check how fonts resolved
55
+
56
+ ```js
57
+ const report = superdoc.fonts.getReport();
58
+ ```
22
59
 
23
- For plain script integrations, load the version-pinned `dist/superdoc-fonts.min.js` browser build and pass `SuperDocFonts.superdocFonts`. Keep the package's `assets/` directory beside `dist/` when self-hosting it.
60
+ The report shows which document fonts were substituted or missing. Compare
61
+ line and page breaks against Word for the documents you care about.
24
62
 
25
- The pack supplies substitutes, not proprietary Microsoft font files, and does not cover every family. It does not guarantee identical Word rendering. Inspect `superdoc.fonts.getReport()` and compare line and page breaks for your documents. Use licensed original files through `fonts.families` when needed.
63
+ ### Use your own licensed fonts
64
+
65
+ The pack supplies substitutes, not Microsoft font files. When you need the
66
+ originals and their license permits web delivery, register them through
67
+ `fonts.families`. See
68
+ [host a proprietary font](https://docs.superdoc.dev/editor/fonts).
69
+
70
+ ### Load without a bundler
71
+
72
+ Load the version-pinned `dist/superdoc-fonts.min.js` browser build and pass
73
+ `SuperDocFonts.superdocFonts`. When self-hosting, keep the package's `assets/`
74
+ directory beside `dist/` so the relative font URLs resolve.
75
+
76
+ ## Common mistakes
77
+
78
+ | Wrong | Right |
79
+ | --- | --- |
80
+ | Expecting identical Word rendering | Substitutes match metrics, not every glyph. Check the font report |
81
+ | Copying font files into `public/` by hand | Let your bundler resolve the package's URLs |
82
+ | Blocking the font origin in your CSP | Allow the origin that serves the fonts |
83
+ | Loading both `@superdoc-dev/fonts` and `@superdoc/fonts` | Use only `@superdoc/fonts` |
84
+ | Expecting fonts like Aptos to be covered | The pack does not cover every family. Host licensed files for the rest |
26
85
 
27
86
  ## Migrating from @superdoc-dev/fonts
28
87
 
@@ -31,6 +90,40 @@ npm uninstall @superdoc-dev/fonts
31
90
  npm install @superdoc/fonts
32
91
  ```
33
92
 
93
+ Change imports from `@superdoc-dev/fonts` to `@superdoc/fonts`. The
94
+ `superdocFonts`, `createSuperDocFonts`, and `resolveBundledFontAssetUrl`
95
+ exports work the same way. Update CDN or self-hosted paths too. New stable
96
+ releases keep publishing the old name as a deprecated mirror, so existing
97
+ installations keep working.
98
+
34
99
  For prereleases, install `@superdoc/fonts@next`.
35
100
 
36
- Change imports from `@superdoc-dev/fonts` to `@superdoc/fonts`. The `superdocFonts`, `createSuperDocFonts`, and `resolveBundledFontAssetUrl` exports retain the same usage. Update CDN or self-hosted paths too, and avoid loading both packages. New stable releases retain the old name as a deprecated compatibility mirror; existing installations keep working.
101
+ ## Related packages
102
+
103
+ - [`superdoc`](https://www.npmjs.com/package/superdoc): the browser DOCX editor these fonts are for.
104
+ - [`@superdoc/react`](https://www.npmjs.com/package/@superdoc/react): accepts the same value as its `fonts` prop.
105
+ - [`@superdoc/vue`](https://www.npmjs.com/package/@superdoc/vue): pass it in the `config` prop as `{ fonts: superdocFonts }`.
106
+
107
+ ## Documentation
108
+
109
+ - [Fonts guide](https://docs.superdoc.dev/editor/fonts)
110
+ - [Package compatibility](https://docs.superdoc.dev/resources/package-compatibility)
111
+ - [`llms.txt`](https://docs.superdoc.dev/llms.txt): machine-readable index of the documentation for coding agents.
112
+
113
+ ## License
114
+
115
+ See [`assets/LICENSES.md`](https://unpkg.com/@superdoc/fonts/assets/LICENSES.md),
116
+ which ships in the package. The bundled fonts keep their own licenses: SIL Open
117
+ Font License, Apache 2.0, AGPL 3.0 with a PostScript/PDF font exception, GPL
118
+ 2.0 with a font exception, and GUST. The license texts sit beside the font
119
+ files.
120
+
121
+ Three families are copyleft: C059 (substitute for Century and Century
122
+ Schoolbook) and URW Gothic (Century Gothic) under AGPL 3.0, and Liberation Sans
123
+ Narrow (Arial Narrow) under GPL 2.0. Their font exceptions mean documents that
124
+ use them are not covered by those licenses. Redistributing the font files
125
+ carries the license's source obligations. To leave them out:
126
+
127
+ ```js
128
+ createSuperDocFonts({ exclude: ['Century', 'Century Schoolbook', 'Century Gothic', 'Arial Narrow'] });
129
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@superdoc/fonts",
3
- "version": "0.5.0",
3
+ "version": "0.6.0-next.9",
4
4
  "description": "Optional bundled metric-compatible font substitutes for SuperDoc, shipped as bundler-resolvable assets.",
5
5
  "type": "module",
6
6
  "license": "SEE LICENSE IN assets/LICENSES.md",