@arraypress/google-fonts 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.
Files changed (5) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +101 -0
  3. package/package.json +25 -0
  4. package/src/index.d.ts +61 -0
  5. package/src/index.js +183 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ArrayPress Limited
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,101 @@
1
+ # @arraypress/google-fonts
2
+
3
+ Google Fonts loader — 32 curated web fonts with on-demand loading, CSS font-family mappings, and deduplication. No framework dependency.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @arraypress/google-fonts
9
+ ```
10
+
11
+ ## Usage
12
+
13
+ ```js
14
+ import { getFontFamily, loadFont, needsLoading, getFontList, FONTS } from '@arraypress/google-fonts';
15
+
16
+ // Get CSS font-family value
17
+ getFontFamily('inter'); // '"Inter", sans-serif'
18
+ getFontFamily('system'); // ''
19
+
20
+ // Load a font (injects <link> into <head>, deduplicates)
21
+ loadFont('inter');
22
+ loadFont('inter'); // no-op, already loaded
23
+
24
+ // Check if a font needs remote loading
25
+ needsLoading('inter'); // true
26
+ needsLoading('system'); // false
27
+
28
+ // Get all fonts for a picker UI
29
+ const fonts = getFontList();
30
+ // [{ key: 'geist', label: 'Geist', family: '"Geist", sans-serif', category: 'sans-serif' }, ...]
31
+ ```
32
+
33
+ ## Available Fonts (32)
34
+
35
+ | Key | Family | Category |
36
+ |-----|--------|----------|
37
+ | `system` | (browser default) | — |
38
+ | `geist` | Geist | sans-serif |
39
+ | `serif` | Playfair Display | serif |
40
+ | `mono` | JetBrains Mono | monospace |
41
+ | `poppins` | Poppins | sans-serif |
42
+ | `inter` | Inter | sans-serif |
43
+ | `dm-sans` | DM Sans | sans-serif |
44
+ | `space-grotesk` | Space Grotesk | sans-serif |
45
+ | `outfit` | Outfit | sans-serif |
46
+ | `plus-jakarta` | Plus Jakarta Sans | sans-serif |
47
+ | `sora` | Sora | sans-serif |
48
+ | `cabinet-grotesk` | Cabinet Grotesk | sans-serif |
49
+ | `montserrat` | Montserrat | sans-serif |
50
+ | `raleway` | Raleway | sans-serif |
51
+ | `lato` | Lato | sans-serif |
52
+ | `open-sans` | Open Sans | sans-serif |
53
+ | `roboto` | Roboto | sans-serif |
54
+ | `nunito` | Nunito | sans-serif |
55
+ | `work-sans` | Work Sans | sans-serif |
56
+ | `rubik` | Rubik | sans-serif |
57
+ | `manrope` | Manrope | sans-serif |
58
+ | `figtree` | Figtree | sans-serif |
59
+ | `onest` | Onest | sans-serif |
60
+ | `lexend` | Lexend | sans-serif |
61
+ | `urbanist` | Urbanist | sans-serif |
62
+ | `quicksand` | Quicksand | sans-serif |
63
+ | `archivo` | Archivo | sans-serif |
64
+ | `barlow` | Barlow | sans-serif |
65
+ | `bricolage-grotesque` | Bricolage Grotesque | sans-serif |
66
+ | `instrument-sans` | Instrument Sans | sans-serif |
67
+ | `crimson-pro` | Crimson Pro | serif |
68
+
69
+ ## API
70
+
71
+ ### `FONTS: Record<string, string>`
72
+
73
+ CSS font-family values for each font key.
74
+
75
+ ### `GOOGLE_FONT_URLS: Record<string, string>`
76
+
77
+ Google Fonts API family strings for loading.
78
+
79
+ ### `FONT_KEYS: string[]`
80
+
81
+ All available font keys.
82
+
83
+ ### `getFontFamily(key: string): string`
84
+
85
+ Get the CSS font-family value for a font key. Returns empty string if not found.
86
+
87
+ ### `loadFont(key: string): void`
88
+
89
+ Load a Google Font by key. Injects a `<link>` tag into `<head>`. Deduplicates. SSR safe.
90
+
91
+ ### `needsLoading(key: string): boolean`
92
+
93
+ Check if a font key needs remote loading from Google Fonts.
94
+
95
+ ### `getFontList(): FontInfo[]`
96
+
97
+ Get font metadata for a picker UI. Returns all fonts except `system`.
98
+
99
+ ## License
100
+
101
+ MIT
package/package.json ADDED
@@ -0,0 +1,25 @@
1
+ {
2
+ "name": "@arraypress/google-fonts",
3
+ "version": "1.0.0",
4
+ "description": "Google Fonts loader — 32 curated web fonts with on-demand loading, CSS font-family mappings, and deduplication.",
5
+ "type": "module",
6
+ "main": "src/index.js",
7
+ "types": "src/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "import": "./src/index.js",
11
+ "types": "./src/index.d.ts"
12
+ }
13
+ },
14
+ "files": ["src"],
15
+ "scripts": {
16
+ "test": "node --test tests/google-fonts.test.js"
17
+ },
18
+ "keywords": ["google-fonts", "fonts", "typography", "css", "web-fonts", "loader"],
19
+ "author": "David Sherlock",
20
+ "license": "MIT",
21
+ "repository": {
22
+ "type": "git",
23
+ "url": "git+https://github.com/arraypress/google-fonts.git"
24
+ }
25
+ }
package/src/index.d.ts ADDED
@@ -0,0 +1,61 @@
1
+ /**
2
+ * @arraypress/google-fonts — TypeScript definitions.
3
+ */
4
+
5
+ /**
6
+ * CSS font-family values for each font key.
7
+ * Keys are lowercase kebab-case identifiers. Values are CSS font-family strings.
8
+ * The `system` key maps to an empty string.
9
+ */
10
+ export declare const FONTS: Record<string, string>;
11
+
12
+ /**
13
+ * Google Fonts API family strings for loading via the CSS2 API.
14
+ * Only fonts that need remote loading are included.
15
+ */
16
+ export declare const GOOGLE_FONT_URLS: Record<string, string>;
17
+
18
+ /**
19
+ * All available font keys including `system`.
20
+ */
21
+ export declare const FONT_KEYS: string[];
22
+
23
+ /**
24
+ * Get the CSS font-family value for a font key.
25
+ * @param key - Font key (e.g. `'inter'`, `'poppins'`, `'system'`).
26
+ * @returns CSS font-family value, or empty string if not found.
27
+ */
28
+ export declare function getFontFamily(key: string): string;
29
+
30
+ /**
31
+ * Load a Google Font by key. Injects a `<link>` tag into `<head>`.
32
+ * Deduplicates — calling multiple times for the same font is safe.
33
+ * No-op in non-browser environments (SSR safe).
34
+ * @param key - Font key from FONTS.
35
+ */
36
+ export declare function loadFont(key: string): void;
37
+
38
+ /**
39
+ * Check if a font key has a Google Fonts URL (needs remote loading).
40
+ * @param key - Font key to check.
41
+ * @returns `true` if the font must be loaded from Google Fonts.
42
+ */
43
+ export declare function needsLoading(key: string): boolean;
44
+
45
+ /** Font metadata for UI display. */
46
+ export interface FontInfo {
47
+ /** Font key (e.g. `'inter'`). */
48
+ key: string;
49
+ /** Human-readable label (e.g. `'Inter'`). */
50
+ label: string;
51
+ /** CSS font-family value. */
52
+ family: string;
53
+ /** Font category: `'serif'`, `'sans-serif'`, or `'monospace'`. */
54
+ category: 'serif' | 'sans-serif' | 'monospace';
55
+ }
56
+
57
+ /**
58
+ * Get font metadata for display in a font picker UI.
59
+ * Returns all fonts except `system`.
60
+ */
61
+ export declare function getFontList(): FontInfo[];
package/src/index.js ADDED
@@ -0,0 +1,183 @@
1
+ /**
2
+ * @arraypress/google-fonts
3
+ *
4
+ * Google Fonts loader — 32 curated web fonts with on-demand loading,
5
+ * CSS font-family mappings, and deduplication. No framework dependency.
6
+ */
7
+
8
+ /**
9
+ * CSS font-family values for each font key.
10
+ *
11
+ * Keys are lowercase kebab-case identifiers used throughout the theme system.
12
+ * Values are CSS `font-family` strings including fallback generic families.
13
+ * The `system` key maps to an empty string (browser default).
14
+ *
15
+ * @type {Record<string, string>}
16
+ */
17
+ export const FONTS = {
18
+ system: '',
19
+ geist: '"Geist", sans-serif',
20
+ serif: '"Playfair Display", serif',
21
+ mono: '"JetBrains Mono", monospace',
22
+ poppins: '"Poppins", sans-serif',
23
+ inter: '"Inter", sans-serif',
24
+ 'dm-sans': '"DM Sans", sans-serif',
25
+ 'space-grotesk': '"Space Grotesk", sans-serif',
26
+ outfit: '"Outfit", sans-serif',
27
+ 'plus-jakarta': '"Plus Jakarta Sans", sans-serif',
28
+ sora: '"Sora", sans-serif',
29
+ 'cabinet-grotesk': '"Cabinet Grotesk", sans-serif',
30
+ montserrat: '"Montserrat", sans-serif',
31
+ raleway: '"Raleway", sans-serif',
32
+ lato: '"Lato", sans-serif',
33
+ 'open-sans': '"Open Sans", sans-serif',
34
+ roboto: '"Roboto", sans-serif',
35
+ nunito: '"Nunito", sans-serif',
36
+ 'work-sans': '"Work Sans", sans-serif',
37
+ rubik: '"Rubik", sans-serif',
38
+ manrope: '"Manrope", sans-serif',
39
+ figtree: '"Figtree", sans-serif',
40
+ onest: '"Onest", sans-serif',
41
+ lexend: '"Lexend", sans-serif',
42
+ urbanist: '"Urbanist", sans-serif',
43
+ quicksand: '"Quicksand", sans-serif',
44
+ archivo: '"Archivo", sans-serif',
45
+ barlow: '"Barlow", sans-serif',
46
+ 'bricolage-grotesque': '"Bricolage Grotesque", sans-serif',
47
+ 'instrument-sans': '"Instrument Sans", sans-serif',
48
+ 'crimson-pro': '"Crimson Pro", serif',
49
+ };
50
+
51
+ /**
52
+ * Google Fonts API family strings for loading via the CSS2 API.
53
+ *
54
+ * Each value is the `family` parameter for `https://fonts.googleapis.com/css2?family=...`.
55
+ * Includes weight axis ranges. Only fonts that need loading from Google are listed
56
+ * (system fonts and locally-hosted fonts are excluded).
57
+ *
58
+ * @type {Record<string, string>}
59
+ */
60
+ export const GOOGLE_FONT_URLS = {
61
+ geist: 'Geist:wght@400;500;600;700;800',
62
+ serif: 'Playfair+Display:wght@400;500;600;700;800;900',
63
+ poppins: 'Poppins:wght@300;400;500;600;700;800',
64
+ inter: 'Inter:wght@300;400;500;600;700;800;900',
65
+ 'dm-sans': 'DM+Sans:wght@300;400;500;600;700',
66
+ 'space-grotesk': 'Space+Grotesk:wght@300;400;500;600;700',
67
+ outfit: 'Outfit:wght@300;400;500;600;700;800',
68
+ 'plus-jakarta': 'Plus+Jakarta+Sans:wght@300;400;500;600;700;800',
69
+ sora: 'Sora:wght@300;400;500;600;700;800',
70
+ montserrat: 'Montserrat:wght@300;400;500;600;700;800;900',
71
+ raleway: 'Raleway:wght@300;400;500;600;700;800;900',
72
+ lato: 'Lato:wght@300;400;700;900',
73
+ 'open-sans': 'Open+Sans:wght@300;400;500;600;700;800',
74
+ roboto: 'Roboto:wght@300;400;500;700;900',
75
+ nunito: 'Nunito:wght@300;400;500;600;700;800;900',
76
+ 'work-sans': 'Work+Sans:wght@300;400;500;600;700;800;900',
77
+ rubik: 'Rubik:wght@300;400;500;600;700;800;900',
78
+ manrope: 'Manrope:wght@300;400;500;600;700;800',
79
+ figtree: 'Figtree:wght@300;400;500;600;700;800',
80
+ onest: 'Onest:wght@300;400;500;600;700;800',
81
+ lexend: 'Lexend:wght@300;400;500;600;700;800',
82
+ urbanist: 'Urbanist:wght@300;400;500;600;700;800',
83
+ quicksand: 'Quicksand:wght@300;400;500;600;700',
84
+ archivo: 'Archivo:wght@300;400;500;600;700;800;900',
85
+ barlow: 'Barlow:wght@300;400;500;600;700;800;900',
86
+ 'bricolage-grotesque': 'Bricolage+Grotesque:wght@300;400;500;600;700;800',
87
+ 'instrument-sans': 'Instrument+Sans:wght@400;500;600;700',
88
+ 'crimson-pro': 'Crimson+Pro:wght@300;400;500;600;700;800',
89
+ };
90
+
91
+ /**
92
+ * All available font keys.
93
+ *
94
+ * Includes `system` (browser default) and all 31 Google Fonts keys.
95
+ *
96
+ * @type {string[]}
97
+ */
98
+ export const FONT_KEYS = Object.keys(FONTS);
99
+
100
+ /**
101
+ * Get the CSS font-family value for a font key.
102
+ *
103
+ * @param {string} key - Font key from FONTS (e.g. `'inter'`, `'poppins'`, `'system'`).
104
+ * @returns {string} CSS font-family value, or empty string if not found.
105
+ *
106
+ * @example
107
+ * getFontFamily('inter'); // '"Inter", sans-serif'
108
+ * getFontFamily('system'); // ''
109
+ * getFontFamily('unknown'); // ''
110
+ */
111
+ export function getFontFamily(key) {
112
+ return FONTS[key] || '';
113
+ }
114
+
115
+ /**
116
+ * Load a Google Font by key. Injects a `<link>` tag into `<head>`.
117
+ *
118
+ * Deduplicates — calling multiple times for the same font is safe.
119
+ * No-op in non-browser environments (SSR safe).
120
+ * No-op for keys without a Google Fonts URL (e.g. `system`, `mono`).
121
+ *
122
+ * @param {string} key - Font key from FONTS (e.g. `'inter'`, `'poppins'`).
123
+ * @returns {void}
124
+ *
125
+ * @example
126
+ * loadFont('inter'); // injects <link> for Inter
127
+ * loadFont('inter'); // no-op, already loaded
128
+ * loadFont('system'); // no-op, no URL
129
+ */
130
+ export function loadFont(key) {
131
+ if (typeof document === 'undefined') return;
132
+ const family = GOOGLE_FONT_URLS[key];
133
+ if (!family) return;
134
+ const id = `gfont-${key}`;
135
+ if (document.getElementById(id)) return;
136
+ const link = document.createElement('link');
137
+ link.id = id;
138
+ link.rel = 'stylesheet';
139
+ link.href = `https://fonts.googleapis.com/css2?family=${family}&display=swap`;
140
+ document.head.appendChild(link);
141
+ }
142
+
143
+ /**
144
+ * Check if a font key has a Google Fonts URL (needs remote loading).
145
+ *
146
+ * System fonts and locally-hosted fonts return `false`.
147
+ *
148
+ * @param {string} key - Font key to check.
149
+ * @returns {boolean} `true` if the font must be loaded from Google Fonts.
150
+ *
151
+ * @example
152
+ * needsLoading('inter'); // true
153
+ * needsLoading('system'); // false
154
+ * needsLoading('mono'); // false (JetBrains Mono has no Google URL in this set)
155
+ */
156
+ export function needsLoading(key) {
157
+ return !!GOOGLE_FONT_URLS[key];
158
+ }
159
+
160
+ /**
161
+ * Get font metadata for display in a font picker UI.
162
+ *
163
+ * Returns an array of objects with `key`, `label`, `family`, and `category`
164
+ * for every font except `system`. Useful for building font selector dropdowns.
165
+ *
166
+ * @returns {Array<{ key: string, label: string, family: string, category: string }>}
167
+ *
168
+ * @example
169
+ * const list = getFontList();
170
+ * // [{ key: 'geist', label: 'Geist', family: '"Geist", sans-serif', category: 'sans-serif' }, ...]
171
+ */
172
+ export function getFontList() {
173
+ return FONT_KEYS.filter(k => k !== 'system').map(key => ({
174
+ key,
175
+ label: key.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' '),
176
+ family: FONTS[key],
177
+ category: FONTS[key].includes('serif') && !FONTS[key].includes('sans-serif')
178
+ ? 'serif'
179
+ : FONTS[key].includes('mono')
180
+ ? 'monospace'
181
+ : 'sans-serif',
182
+ }));
183
+ }