@superdoc/fonts 0.3.0-next.1

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 (96) hide show
  1. package/LICENSE +661 -0
  2. package/README.md +36 -0
  3. package/assets/AGPL-3.0.txt +228 -0
  4. package/assets/Apache-2.0.txt +204 -0
  5. package/assets/ArchivoBlack-Regular.woff2 +0 -0
  6. package/assets/BacasimeAntique-Regular.woff2 +0 -0
  7. package/assets/C059-BdIta.woff2 +0 -0
  8. package/assets/C059-Bold.woff2 +0 -0
  9. package/assets/C059-Italic.woff2 +0 -0
  10. package/assets/C059-Roman.woff2 +0 -0
  11. package/assets/Caladea-Bold.woff2 +0 -0
  12. package/assets/Caladea-BoldItalic.woff2 +0 -0
  13. package/assets/Caladea-Italic.woff2 +0 -0
  14. package/assets/Caladea-Regular.woff2 +0 -0
  15. package/assets/Caprasimo-Regular.woff2 +0 -0
  16. package/assets/Cardo-Bold.woff2 +0 -0
  17. package/assets/Cardo-Italic.woff2 +0 -0
  18. package/assets/Cardo-Regular.woff2 +0 -0
  19. package/assets/Carlito-Bold.woff2 +0 -0
  20. package/assets/Carlito-BoldItalic.woff2 +0 -0
  21. package/assets/Carlito-Italic.woff2 +0 -0
  22. package/assets/Carlito-Regular.woff2 +0 -0
  23. package/assets/ComicRelief-Bold.woff2 +0 -0
  24. package/assets/ComicRelief-Regular.woff2 +0 -0
  25. package/assets/GPL-2.0.txt +116 -0
  26. package/assets/GUST-Font-License-1.0.txt +28 -0
  27. package/assets/Gelasio-Bold.woff2 +0 -0
  28. package/assets/Gelasio-BoldItalic.woff2 +0 -0
  29. package/assets/Gelasio-Italic.woff2 +0 -0
  30. package/assets/Gelasio-Regular.woff2 +0 -0
  31. package/assets/InconsolataSemiExpanded-Bold.woff2 +0 -0
  32. package/assets/InconsolataSemiExpanded-Regular.woff2 +0 -0
  33. package/assets/LICENSES.md +329 -0
  34. package/assets/LiberationMono-Bold.woff2 +0 -0
  35. package/assets/LiberationMono-BoldItalic.woff2 +0 -0
  36. package/assets/LiberationMono-Italic.woff2 +0 -0
  37. package/assets/LiberationMono-Regular.woff2 +0 -0
  38. package/assets/LiberationSans-Bold.woff2 +0 -0
  39. package/assets/LiberationSans-BoldItalic.woff2 +0 -0
  40. package/assets/LiberationSans-Italic.woff2 +0 -0
  41. package/assets/LiberationSans-Regular.woff2 +0 -0
  42. package/assets/LiberationSansNarrow-Bold.woff2 +0 -0
  43. package/assets/LiberationSansNarrow-BoldItalic.woff2 +0 -0
  44. package/assets/LiberationSansNarrow-Italic.woff2 +0 -0
  45. package/assets/LiberationSansNarrow-Regular.woff2 +0 -0
  46. package/assets/LiberationSerif-Bold.woff2 +0 -0
  47. package/assets/LiberationSerif-BoldItalic.woff2 +0 -0
  48. package/assets/LiberationSerif-Italic.woff2 +0 -0
  49. package/assets/LiberationSerif-Regular.woff2 +0 -0
  50. package/assets/NotoSans-Bold.woff2 +0 -0
  51. package/assets/NotoSans-BoldItalic.woff2 +0 -0
  52. package/assets/NotoSans-Italic.woff2 +0 -0
  53. package/assets/NotoSans-Regular.woff2 +0 -0
  54. package/assets/NotoSansMono-Bold.woff2 +0 -0
  55. package/assets/NotoSansMono-Regular.woff2 +0 -0
  56. package/assets/OFL.txt +199 -0
  57. package/assets/OreganoItalic-Regular.woff2 +0 -0
  58. package/assets/PTSans-Bold.woff2 +0 -0
  59. package/assets/PTSans-BoldItalic.woff2 +0 -0
  60. package/assets/PTSans-Italic.woff2 +0 -0
  61. package/assets/PTSans-Regular.woff2 +0 -0
  62. package/assets/PTSansNarrow-Bold.woff2 +0 -0
  63. package/assets/PTSansNarrow-Regular.woff2 +0 -0
  64. package/assets/Selawik-Bold.woff2 +0 -0
  65. package/assets/Selawik-Regular.woff2 +0 -0
  66. package/assets/TeXGyreBonum-Bold.woff2 +0 -0
  67. package/assets/TeXGyreBonum-BoldItalic.woff2 +0 -0
  68. package/assets/TeXGyreBonum-Italic.woff2 +0 -0
  69. package/assets/TeXGyreBonum-Regular.woff2 +0 -0
  70. package/assets/URWGothic-Book.woff2 +0 -0
  71. package/assets/URWGothic-BookOblique.woff2 +0 -0
  72. package/assets/URWGothic-Demi.woff2 +0 -0
  73. package/assets/URWGothic-DemiOblique.woff2 +0 -0
  74. package/dist/asset-urls.d.ts +8 -0
  75. package/dist/asset-urls.js +76 -0
  76. package/dist/bundled-families.d.ts +15 -0
  77. package/dist/bundled-families.js +40 -0
  78. package/dist/bundled-files.d.ts +8 -0
  79. package/dist/bundled-files.js +74 -0
  80. package/dist/cdn-entry.d.ts +27 -0
  81. package/dist/cdn-entry.js +67 -0
  82. package/dist/curation.d.ts +66 -0
  83. package/dist/curation.js +102 -0
  84. package/dist/index.d.ts +71 -0
  85. package/dist/index.js +81 -0
  86. package/dist/superdoc-fonts.min.js +3 -0
  87. package/dist/superdoc-fonts.min.js.map +1 -0
  88. package/package.json +52 -0
  89. package/src/asset-urls.ts +76 -0
  90. package/src/bundled-families.ts +47 -0
  91. package/src/bundled-files.ts +74 -0
  92. package/src/cdn-entry.test.ts +48 -0
  93. package/src/cdn-entry.ts +84 -0
  94. package/src/curation.ts +158 -0
  95. package/src/index.test.ts +87 -0
  96. package/src/index.ts +96 -0
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Browser / `<script>` (IIFE) entry for `@superdoc/fonts`, built to
3
+ * `dist/superdoc-fonts.min.js` and exposed as the `SuperDocFonts` global.
4
+ *
5
+ * Unlike the bundler entry ({@link "./index"}), it resolves the `.woff2` relative to its OWN
6
+ * `<script>` (`document.currentScript`) instead of `import.meta.url`, so a plain CDN / self-host
7
+ * `<script>` tag works with no bundler:
8
+ *
9
+ * <script src="https://cdn.jsdelivr.net/npm/superdoc@next/dist-cdn/superdoc.min.js"></script>
10
+ * <script src="https://cdn.jsdelivr.net/npm/@superdoc/fonts/dist/superdoc-fonts.min.js"></script>
11
+ * <script>
12
+ * new SuperDoc({ selector: '#editor', document: 'contract.docx', fonts: SuperDocFonts.superdocFonts });
13
+ * </script>
14
+ *
15
+ * The faces ship in the package's `assets/` dir and this bundle in `dist/`, so a face resolves to
16
+ * `../assets/<file>` relative to the script. On a public CDN (jsDelivr / unpkg) the whole package
17
+ * is served, so that resolves with no setup; self-hosting requires the `dist/` and `assets/` dirs
18
+ * to keep their relative layout.
19
+ *
20
+ * @beta
21
+ */
22
+ import { BUNDLED_FONT_FILES } from './bundled-files.js';
23
+ import {
24
+ resolveCuration,
25
+ type BundledFontAssetContext,
26
+ type SuperDocFontsConfig,
27
+ type SuperDocFontsOptions,
28
+ } from './curation.js';
29
+
30
+ // Capture the executing <script> src at load. `document.currentScript` is valid while this
31
+ // top-level IIFE runs and null later (e.g. in async callbacks), so it MUST be read here, at module
32
+ // eval, not inside the resolver. Duck-typed (no `instanceof HTMLScriptElement`) so the module also
33
+ // evaluates under a non-DOM test environment where that constructor is absent.
34
+ const currentScript = typeof document !== 'undefined' ? (document.currentScript as { src?: string } | null) : null;
35
+ const SCRIPT_SRC: string = currentScript?.src ?? '';
36
+
37
+ const KNOWN_FILES: ReadonlySet<string> = new Set(BUNDLED_FONT_FILES);
38
+
39
+ /**
40
+ * Resolve a bundled face filename to a URL relative to THIS script. Throws on an unknown file
41
+ * (a version mismatch between `@superdoc/fonts` and `superdoc`) and on a missing script URL,
42
+ * matching the bundler entry's fail-loud-not-silent contract.
43
+ *
44
+ * @beta
45
+ */
46
+ export function resolveBundledFontAssetUrl(context: BundledFontAssetContext): string {
47
+ if (!KNOWN_FILES.has(context.file)) {
48
+ throw new Error(
49
+ `[@superdoc/fonts] no bundled asset for "${context.file}". This pack ships ` +
50
+ `${BUNDLED_FONT_FILES.length} faces; the file is unknown, so @superdoc/fonts and ` +
51
+ `superdoc are likely version-mismatched. Align their versions.`,
52
+ );
53
+ }
54
+ if (!SCRIPT_SRC) {
55
+ throw new Error(
56
+ '[@superdoc/fonts] could not determine the script URL to resolve bundled fonts from. ' +
57
+ 'Load superdoc-fonts.min.js with a normal <script src="..."> tag.',
58
+ );
59
+ }
60
+ return new URL(`../assets/${context.file}`, SCRIPT_SRC).href;
61
+ }
62
+
63
+ /**
64
+ * Drop-in value for SuperDoc's `fonts` config: `new SuperDoc({ fonts: SuperDocFonts.superdocFonts })`.
65
+ *
66
+ * @beta
67
+ */
68
+ export const superdocFonts: SuperDocFontsConfig = { resolveAssetUrl: resolveBundledFontAssetUrl };
69
+
70
+ /**
71
+ * Build a curated `fonts` config: the bundled pack narrowed to the families you choose. Same API
72
+ * and validation as the bundler entry's `createSuperDocFonts`; only the resolver differs.
73
+ *
74
+ * new SuperDoc({ fonts: SuperDocFonts.createSuperDocFonts({ exclude: ['Cooper Black'] }) });
75
+ *
76
+ * @beta
77
+ */
78
+ export function createSuperDocFonts(options: SuperDocFontsOptions = {}): SuperDocFontsConfig {
79
+ return { resolveAssetUrl: resolveBundledFontAssetUrl, ...resolveCuration(options) };
80
+ }
81
+
82
+ export type { BundledFontAssetContext, SuperDocFontsConfig, SuperDocFontsOptions };
83
+ export { BUNDLED_FAMILY_NAMES } from './bundled-families.js';
84
+ export type { BundledFontFamilyName } from './bundled-families.js';
@@ -0,0 +1,158 @@
1
+ /**
2
+ * Resolver-independent curation + validation shared by the two entries: the bundler entry
3
+ * (`index.ts`, asset URLs via `import.meta.url`) and the browser/IIFE entry (`cdn-entry.ts`, URLs
4
+ * relative to its own `<script>`). Each entry supplies only its own asset-URL resolver; the
5
+ * `include` / `exclude` validation lives here once so the two entries can never drift.
6
+ *
7
+ * @beta
8
+ */
9
+ import { BUNDLED_FAMILY_NAMES, type BundledFontFamilyName } from './bundled-families.js';
10
+
11
+ /**
12
+ * Minimal structural shape of SuperDoc's bundled-font asset context. Kept LOCAL so this package
13
+ * has no dependency on `@superdoc/font-system`; only `file` is read. Assignable to SuperDoc's
14
+ * `FontAssetUrlResolver` by structural typing.
15
+ *
16
+ * @beta
17
+ */
18
+ export interface BundledFontAssetContext {
19
+ /** Asset filename, e.g. `Carlito-Regular.woff2`. */
20
+ file: string;
21
+ family?: string;
22
+ weight?: string;
23
+ style?: 'normal' | 'italic';
24
+ source?: string;
25
+ }
26
+
27
+ /** Per-face asset-URL resolver: maps a bundled face filename to a URL the browser can fetch. */
28
+ export type BundledFontAssetResolver = (context: BundledFontAssetContext) => string;
29
+
30
+ /**
31
+ * Choose which bundled families SuperDoc advertises and renders, by LOGICAL Word family name
32
+ * (`"Calibri"`, never the physical `"Carlito"`).
33
+ *
34
+ * @beta
35
+ */
36
+ export interface SuperDocFontsOptions {
37
+ /**
38
+ * Allow-list: ONLY these logical families are active, e.g. `['Calibri', 'Cambria']`. Autocompletes
39
+ * the bundled names, but also accepts any string (case- and quote-insensitive, validated at
40
+ * runtime), so a list built from dynamic config still type-checks.
41
+ */
42
+ include?: readonly (BundledFontFamilyName | (string & {}))[];
43
+ /** Block-list: every bundled family EXCEPT these, e.g. `['Cooper Black', 'Brush Script MT']`. */
44
+ exclude?: readonly (BundledFontFamilyName | (string & {}))[];
45
+ }
46
+
47
+ /**
48
+ * The `fonts` config the entries return: the bundled-asset resolver plus the curation.
49
+ * Structurally assignable to SuperDoc's `fonts` option.
50
+ *
51
+ * @beta
52
+ */
53
+ export interface SuperDocFontsConfig {
54
+ resolveAssetUrl: BundledFontAssetResolver;
55
+ bundled?: { include?: string[]; exclude?: string[] };
56
+ [key: string]: unknown;
57
+ }
58
+
59
+ /**
60
+ * Validate the curation options and return the `{ bundled? }` slice (no resolver). Each entry
61
+ * spreads this into its own `{ resolveAssetUrl, ...resolveCuration(options) }`.
62
+ */
63
+ export function resolveCuration(options: SuperDocFontsOptions = {}): {
64
+ bundled?: { include?: string[]; exclude?: string[] };
65
+ } {
66
+ const include = normalizeNameList(options.include, 'include');
67
+ const exclude = normalizeNameList(options.exclude, 'exclude');
68
+ // include and exclude are mutually exclusive intents; accepting both silently would hide which one
69
+ // wins. Reject at the API boundary (this runs in the consumer's setup code, so it fails fast and
70
+ // clearly) rather than picking one arbitrarily.
71
+ if (include && exclude) {
72
+ throw new Error(
73
+ '[@superdoc/fonts] createSuperDocFonts: pass `include` OR `exclude`, not both. ' +
74
+ '`include` is an allow-list (only those families resolve and appear in the toolbar); ' +
75
+ '`exclude` keeps everything but the named families.',
76
+ );
77
+ }
78
+ // Reject names SuperDoc does not bundle. This runs in the consumer's setup code, so it fails fast
79
+ // and clearly - especially for `include`, where a typo would otherwise silently hide the fonts the
80
+ // consumer meant to keep. (Raw `fonts.bundled` set directly stays lenient and only warns.)
81
+ if (include) assertKnownFamilies(include, 'include');
82
+ if (exclude) assertKnownFamilies(exclude, 'exclude');
83
+ if (include) return { bundled: { include } };
84
+ if (exclude) return { bundled: { exclude } };
85
+ return {};
86
+ }
87
+
88
+ /** Validate and clean a curation list: an array of non-empty strings, or omitted. Throws on misuse. */
89
+ function normalizeNameList(value: readonly string[] | undefined, field: 'include' | 'exclude'): string[] | undefined {
90
+ if (value == null) return undefined;
91
+ if (!Array.isArray(value)) {
92
+ throw new Error(`[@superdoc/fonts] createSuperDocFonts: \`${field}\` must be an array of Word font names.`);
93
+ }
94
+ const names = value.map((name) => (typeof name === 'string' ? name.trim() : '')).filter(Boolean);
95
+ if (names.length !== value.length) {
96
+ throw new Error(
97
+ `[@superdoc/fonts] createSuperDocFonts: \`${field}\` must contain only non-empty font name strings ` +
98
+ `(e.g. ["Calibri", "Cambria"]).`,
99
+ );
100
+ }
101
+ return names.length ? names : undefined;
102
+ }
103
+
104
+ /** Normalize a family name for matching: trim, strip surrounding quotes, lowercase. */
105
+ function normalizeKey(name: string): string {
106
+ return name
107
+ .trim()
108
+ .replace(/^["']|["']$/g, '')
109
+ .toLowerCase();
110
+ }
111
+
112
+ const KNOWN_FAMILY_KEYS: ReadonlySet<string> = new Set(BUNDLED_FAMILY_NAMES.map(normalizeKey));
113
+
114
+ /** Bounded Levenshtein distance between two short strings, for a "did you mean" hint on a typo. */
115
+ function editDistance(a: string, b: string): number {
116
+ const m = a.length;
117
+ const n = b.length;
118
+ if (Math.abs(m - n) > 2) return 3;
119
+ let prev = Array.from({ length: n + 1 }, (_, i) => i);
120
+ for (let i = 1; i <= m; i += 1) {
121
+ const curr = [i];
122
+ for (let j = 1; j <= n; j += 1) {
123
+ const cost = a[i - 1] === b[j - 1] ? 0 : 1;
124
+ curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
125
+ }
126
+ prev = curr;
127
+ }
128
+ return prev[n];
129
+ }
130
+
131
+ /** The closest bundled family within edit distance 2, or null - so a typo gets a concrete suggestion. */
132
+ function closestKnownFamily(name: string): string | null {
133
+ const key = normalizeKey(name);
134
+ let best: string | null = null;
135
+ let bestDist = 3;
136
+ for (const family of BUNDLED_FAMILY_NAMES) {
137
+ const dist = editDistance(key, normalizeKey(family));
138
+ if (dist < bestDist) {
139
+ bestDist = dist;
140
+ best = family;
141
+ }
142
+ }
143
+ return best;
144
+ }
145
+
146
+ /** Throw on any curation name SuperDoc does not bundle, with a suggestion and the full valid list. */
147
+ function assertKnownFamilies(names: readonly string[], field: 'include' | 'exclude'): void {
148
+ const unknown = names.filter((name) => !KNOWN_FAMILY_KEYS.has(normalizeKey(name)));
149
+ if (unknown.length === 0) return;
150
+ const hints = unknown.map((name) => {
151
+ const suggestion = closestKnownFamily(name);
152
+ return suggestion ? `"${name}" (did you mean "${suggestion}"?)` : `"${name}"`;
153
+ });
154
+ throw new Error(
155
+ `[@superdoc/fonts] createSuperDocFonts: \`${field}\` names a font SuperDoc does not bundle: ${hints.join(', ')}. ` +
156
+ `Curate by Word family name. Bundled families: ${BUNDLED_FAMILY_NAMES.join(', ')}.`,
157
+ );
158
+ }
@@ -0,0 +1,87 @@
1
+ import { describe, expect, it } from 'vite-plus/test';
2
+ import {
3
+ BUNDLED_FAMILY_NAMES,
4
+ BUNDLED_FONT_ASSET_URLS,
5
+ createSuperDocFonts,
6
+ resolveBundledFontAssetUrl,
7
+ superdocFonts,
8
+ } from './index';
9
+
10
+ describe('superdocFonts / resolveBundledFontAssetUrl', () => {
11
+ it('superdocFonts is a ready-made resolveAssetUrl config', () => {
12
+ expect(typeof superdocFonts.resolveAssetUrl).toBe('function');
13
+ });
14
+
15
+ it('resolves a known bundled face to its emitted URL', () => {
16
+ const file = Object.keys(BUNDLED_FONT_ASSET_URLS)[0];
17
+ expect(file).toBeTruthy();
18
+ expect(superdocFonts.resolveAssetUrl({ file })).toBe(BUNDLED_FONT_ASSET_URLS[file]);
19
+ });
20
+
21
+ it('throws on an unknown file so a version mismatch surfaces immediately', () => {
22
+ expect(() => resolveBundledFontAssetUrl({ file: 'NotAFont.woff2' })).toThrow(/no bundled asset/);
23
+ });
24
+ });
25
+
26
+ describe('createSuperDocFonts', () => {
27
+ it('with no options is the full pack: resolver only, no curation', () => {
28
+ const config = createSuperDocFonts();
29
+ expect(typeof config.resolveAssetUrl).toBe('function');
30
+ expect(config.bundled).toBeUndefined();
31
+ });
32
+
33
+ it('include sets an allow-list', () => {
34
+ expect(createSuperDocFonts({ include: ['Calibri', 'Cambria'] }).bundled).toEqual({
35
+ include: ['Calibri', 'Cambria'],
36
+ });
37
+ });
38
+
39
+ it('exclude sets a block-list', () => {
40
+ expect(createSuperDocFonts({ exclude: ['Cooper Black'] }).bundled).toEqual({ exclude: ['Cooper Black'] });
41
+ });
42
+
43
+ it('trims entries and drops empty lists', () => {
44
+ expect(createSuperDocFonts({ include: [' Calibri '] }).bundled).toEqual({ include: ['Calibri'] });
45
+ expect(createSuperDocFonts({ include: [] }).bundled).toBeUndefined();
46
+ expect(createSuperDocFonts({ exclude: [] }).bundled).toBeUndefined();
47
+ });
48
+
49
+ it('throws when include and exclude are both given (mutually exclusive intents)', () => {
50
+ expect(() => createSuperDocFonts({ include: ['Calibri'], exclude: ['Cambria'] })).toThrow(/not both/);
51
+ });
52
+
53
+ it('throws on a non-array list or non-string entries', () => {
54
+ expect(() => createSuperDocFonts({ include: 'Calibri' as unknown as string[] })).toThrow(/must be an array/);
55
+ expect(() => createSuperDocFonts({ exclude: ['Calibri', 42 as unknown as string] })).toThrow(
56
+ /non-empty font name strings/,
57
+ );
58
+ });
59
+
60
+ it('throws on a font name SuperDoc does not bundle, suggesting the closest match for a typo', () => {
61
+ expect(() => createSuperDocFonts({ include: ['Calbri'] })).toThrow(/does not bundle/);
62
+ expect(() => createSuperDocFonts({ include: ['Calbri'] })).toThrow(/did you mean "Calibri"\?/);
63
+ // A real Word font with no bundled clone is also rejected (curating it would be a no-op).
64
+ expect(() => createSuperDocFonts({ exclude: ['Aptos'] })).toThrow(/does not bundle/);
65
+ });
66
+
67
+ it('accepts every family the toolbar advertises, including category fallbacks like Verdana', () => {
68
+ // Regression: the curatable list must mirror the resolver/offerings, not the manifest's narrower
69
+ // metric-clone `replaces` (which omits Verdana). A font shown in the toolbar must be curatable.
70
+ expect(() => createSuperDocFonts({ exclude: ['Verdana'] })).not.toThrow();
71
+ expect(() => createSuperDocFonts({ include: ['Verdana', 'Calibri'] })).not.toThrow();
72
+ expect(createSuperDocFonts({ exclude: ['Verdana'] }).bundled).toEqual({ exclude: ['Verdana'] });
73
+ });
74
+
75
+ it('accepts case- and quote-variant spellings of bundled families (matched normalized)', () => {
76
+ expect(() => createSuperDocFonts({ include: [' calibri ', '"Cambria"'] })).not.toThrow();
77
+ });
78
+ });
79
+
80
+ describe('BUNDLED_FAMILY_NAMES', () => {
81
+ it('is exported as a non-empty list of curatable Word family names', () => {
82
+ expect(BUNDLED_FAMILY_NAMES.length).toBeGreaterThan(0);
83
+ expect(BUNDLED_FAMILY_NAMES).toContain('Calibri');
84
+ // Every advertised name is accepted by the curation API (the list and the validator agree).
85
+ expect(() => createSuperDocFonts({ include: [...BUNDLED_FAMILY_NAMES] })).not.toThrow();
86
+ });
87
+ });
package/src/index.ts ADDED
@@ -0,0 +1,96 @@
1
+ /**
2
+ * `@superdoc/fonts` - the reviewed metric-compatible font substitutes SuperDoc renders for
3
+ * proprietary Word fonts (Carlito for Calibri, Liberation Serif for Times New Roman, etc.).
4
+ *
5
+ * Optional: install it to make the bundled fallbacks load automatically in any bundler app, with
6
+ * no copy step and no `assetBaseUrl`. The asset URLs are written as
7
+ * `new URL('../assets/<file>', import.meta.url)`, which Vite, Webpack 5, Next, Nuxt, esbuild, and
8
+ * Parcel detect, emit, and rewrite to the final hashed path.
9
+ *
10
+ * For a plain `<script>` / CDN page (no bundler), load `dist/superdoc-fonts.min.js` instead and use
11
+ * the `SuperDocFonts` global - same API, faces resolved relative to the script. See `cdn-entry.ts`.
12
+ *
13
+ * @beta This package is in preview; its surface may change before 1.0.
14
+ */
15
+ import { BUNDLED_FONT_ASSET_URLS } from './asset-urls.js';
16
+ import {
17
+ resolveCuration,
18
+ type BundledFontAssetContext,
19
+ type SuperDocFontsConfig,
20
+ type SuperDocFontsOptions,
21
+ } from './curation.js';
22
+
23
+ /**
24
+ * The full filename -> bundler-emitted URL map for every bundled face. Most consumers use
25
+ * {@link superdocFonts} or {@link resolveBundledFontAssetUrl} instead of reading this directly.
26
+ *
27
+ * @beta
28
+ */
29
+ export { BUNDLED_FONT_ASSET_URLS };
30
+
31
+ export type { BundledFontAssetContext, SuperDocFontsConfig, SuperDocFontsOptions };
32
+
33
+ /**
34
+ * The curatable Word family names (and their union type), for building `include` / `exclude` lists
35
+ * with autocomplete. Re-exported from the generated source.
36
+ *
37
+ * @beta
38
+ */
39
+ export { BUNDLED_FAMILY_NAMES } from './bundled-families.js';
40
+ export type { BundledFontFamilyName } from './bundled-families.js';
41
+
42
+ /**
43
+ * Resolve a bundled substitute face filename to a bundler-emitted URL.
44
+ *
45
+ * Pass as SuperDoc's `fonts.resolveAssetUrl` so the reviewed fallback pack loads from THIS
46
+ * package's emitted assets, with no manual copy step and no `assetBaseUrl`:
47
+ *
48
+ * import { resolveBundledFontAssetUrl } from '@superdoc/fonts';
49
+ * new SuperDoc({ selector: '#editor', document, fonts: { resolveAssetUrl: resolveBundledFontAssetUrl } });
50
+ *
51
+ * Throws on an unknown file, which signals a version mismatch between `@superdoc/fonts` and
52
+ * the `superdoc` core manifest rather than silently degrading to the logical font name.
53
+ *
54
+ * @beta
55
+ */
56
+ export function resolveBundledFontAssetUrl(context: BundledFontAssetContext): string {
57
+ const url = BUNDLED_FONT_ASSET_URLS[context.file];
58
+ if (!url) {
59
+ throw new Error(
60
+ `[@superdoc/fonts] no bundled asset for "${context.file}". This pack ships ` +
61
+ `${Object.keys(BUNDLED_FONT_ASSET_URLS).length} faces; the file is unknown, so ` +
62
+ `@superdoc/fonts and superdoc are likely version-mismatched. Align their versions.`,
63
+ );
64
+ }
65
+ return url;
66
+ }
67
+
68
+ /**
69
+ * Drop-in value for SuperDoc's `fonts` config: `new SuperDoc({ fonts: superdocFonts })`.
70
+ * Equivalent to `{ resolveAssetUrl: resolveBundledFontAssetUrl }`.
71
+ *
72
+ * @beta
73
+ */
74
+ export const superdocFonts: SuperDocFontsConfig = {
75
+ resolveAssetUrl: resolveBundledFontAssetUrl,
76
+ };
77
+
78
+ /**
79
+ * Build a curated `fonts` config: the bundled pack, narrowed to the families you choose.
80
+ *
81
+ * import { createSuperDocFonts } from '@superdoc/fonts';
82
+ * new SuperDoc({
83
+ * selector: '#editor',
84
+ * document,
85
+ * fonts: createSuperDocFonts({ exclude: ['Cooper Black', 'Brush Script MT'] }),
86
+ * });
87
+ *
88
+ * Names are Word logical families. Pass neither `include` nor `exclude` for the full pack - that is
89
+ * exactly {@link superdocFonts}. Curation governs the BUNDLED pack only; your own licensed fonts stay
90
+ * separate (`fonts.families` / `fonts.map`).
91
+ *
92
+ * @beta
93
+ */
94
+ export function createSuperDocFonts(options: SuperDocFontsOptions = {}): SuperDocFontsConfig {
95
+ return { resolveAssetUrl: resolveBundledFontAssetUrl, ...resolveCuration(options) };
96
+ }