fontdue-js 3.0.0-alpha4 → 3.0.0-alpha5

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 (33) hide show
  1. package/README.md +463 -94
  2. package/dist/__generated__/ServerConfigProviderQuery.graphql.js +8 -1
  3. package/dist/__generated__/TestModeBannerQuery.graphql.js +8 -1
  4. package/dist/__generated__/ThemeConfigQuery.graphql.js +8 -1
  5. package/dist/__tests__/licenseExclusions.test.js +161 -0
  6. package/dist/components/BuyButton/index.d.ts +2 -2
  7. package/dist/components/BuyButton/index.js +3 -3
  8. package/dist/components/CartButton/index.d.ts +1 -11
  9. package/dist/components/CartButton/index.js +9 -29
  10. package/dist/components/CartButton/index.server.d.ts +1 -3
  11. package/dist/components/CartButton/index.server.js +14 -20
  12. package/dist/components/CharacterViewer/index.d.ts +2 -2
  13. package/dist/components/CharacterViewer/index.js +3 -3
  14. package/dist/components/FontdueProvider/FontdueProviderClientComponent.d.ts +4 -6
  15. package/dist/components/FontdueProvider/FontdueProviderClientComponent.js +39 -48
  16. package/dist/components/FontdueProvider/index.server.js +1 -3
  17. package/dist/components/NewsletterSignup/index.d.ts +2 -2
  18. package/dist/components/NewsletterSignup/index.js +2 -2
  19. package/dist/components/TestFontsForm/index.d.ts +2 -2
  20. package/dist/components/TestFontsForm/index.js +2 -2
  21. package/dist/components/ThemeConfig/index.server.js +14 -7
  22. package/dist/components/TypeTester/TypeTesterStandalone.d.ts +2 -2
  23. package/dist/components/TypeTester/TypeTesterStandalone.js +2 -2
  24. package/dist/components/TypeTesters/index.d.ts +2 -2
  25. package/dist/components/TypeTesters/index.js +3 -3
  26. package/dist/fontdue.css +12 -12
  27. package/dist/loadFontdueProviderQuery.d.ts +1 -2
  28. package/dist/loadFontdueProviderQuery.js +2 -2
  29. package/dist/relay/environment.js +1 -1
  30. package/dist/relay/loadSerializableQuery.d.ts +1 -5
  31. package/dist/relay/loadSerializableQuery.js +2 -2
  32. package/dist/vite.js +42 -2
  33. package/package.json +3 -6
package/README.md CHANGED
@@ -1,44 +1,59 @@
1
1
  # fontdue-js
2
2
 
3
- This package exports [Fontdue.js](https://docs.fontdue.com/fontduejs) components for React projects.
3
+ React components for [Fontdue](https://fontdue.com) sites. Framework-agnostic: works in Next.js, Astro, React Router 7, TanStack Start, Vike, Remix, and any other React SSR or client-only environment.
4
4
 
5
5
  ## Requirements
6
6
 
7
- - `react` >= 18
8
- - `node` >= 16
9
-
10
- If using TypeScript, update to >= 4.7 and change your `tsconfig.json` moduleResolution setting to `node16`:
11
-
12
- ``` json
7
+ - `react` 18 or 19
8
+ - `node` >= 18
9
+ - TypeScript (if used) with `moduleResolution` set to `node16`, `nodenext`, or `bundler` so the package's `exports` map resolves:
13
10
 
11
+ ```json
14
12
  {
15
13
  "compilerOptions": {
16
- "moduleResolution": "node16",
14
+ "moduleResolution": "nodenext"
17
15
  }
18
16
  }
19
-
20
17
  ```
21
18
 
19
+ `fontdue-js` is published ESM-only.
20
+
22
21
  ## Installation
23
22
 
24
- ``` shell
23
+ ```shell
25
24
  npm install fontdue-js@latest
26
25
  ```
27
26
 
28
- ## Usage
27
+ ## Configuration
29
28
 
30
- 1. Wrap the root of your project with the [`FontdueProvider`](#fontdueprovider) component. For example in a Next.js app, add it to your `app/layout.tsx` or `pages/_app.tsx`.
31
- 2. If using Next.js, add an environment variable to your app `NEXT_PUBLIC_FONTDUE_URL` pointing to your Fontdue store URL. Otherwise, you can include the `url` prop on the `FontdueProvider`.
32
- 3. Render the [`StoreModal`](#storemodal) component so that is it available on every page.
33
- 4. Import the `fontdue-js/fontdue.css` CSS file. (This example uses Next.js)
29
+ Point fontdue-js at your Fontdue URL via an environment variable. Pick the one your framework already uses for public env vars:
34
30
 
35
- ### Example
31
+ | Framework | Variable |
32
+ | --- | --- |
33
+ | Astro | `PUBLIC_FONTDUE_URL` |
34
+ | React Router 7 / TanStack Start / Vike / Remix (Vite) | `VITE_FONTDUE_URL` |
35
+ | Next.js | `NEXT_PUBLIC_FONTDUE_URL` |
36
+ | Other / framework-less SSR | `FONTDUE_URL` |
36
37
 
38
+ A single variable covers both server and client in every supported framework — Vite exposes `import.meta.env.PUBLIC_*` / `VITE_*` on both sides, and Next inlines `NEXT_PUBLIC_*` on both sides.
37
39
 
38
- ``` shell
39
- # .env.local
40
- NEXT_PUBLIC_FONTDUE_URL=https://example.fontdue.com
41
- ```
40
+ ## Setup
41
+
42
+ Pick the section that matches your framework. All four examples below have a working repo linked at the bottom.
43
+
44
+ The general pattern in every framework:
45
+
46
+ 1. Mount `<FontdueProvider>` once at the layout level — it sets up the Relay environment + Redux store and renders auxiliary UI (theme config, test-mode banner, consent banner, analytics tracking).
47
+ 2. Mount `<StoreModal />` once, alongside the provider — opens when a `<BuyButton>` or `<CartButton>` is clicked.
48
+ 3. (SSR only.) Preload in the layout with `loadFontdueProviderQuery()` and pass it as `<FontdueProvider preloadedQuery={…}>`. This ensures the page hydrates with preloaded data.
49
+ 4. (SSR only.) Preload per-page components with their `load{Component}Query()` helpers in route loaders / frontmatter / server components.
50
+
51
+ The shape of step 3 and 4 is the only thing that changes between frameworks.
52
+
53
+ <details>
54
+ <summary><b>Next.js (App Router)</b></summary>
55
+
56
+ No Vite plugin needed. The simplest setup omits the layout preload — with React Server Components, each fontdue-js component preloads its own query internally on the server and streams to the client.
42
57
 
43
58
  ```tsx
44
59
  // app/layout.tsx
@@ -46,17 +61,12 @@ import FontdueProvider from "fontdue-js/FontdueProvider";
46
61
  import StoreModal from "fontdue-js/StoreModal";
47
62
  import "fontdue-js/fontdue.css";
48
63
 
49
- export default async function RootLayout({
50
- children,
51
- }: {
52
- children: React.ReactNode;
53
- }) {
64
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
54
65
  return (
55
66
  <html lang="en">
56
67
  <body>
57
68
  <FontdueProvider>
58
69
  {children}
59
-
60
70
  <StoreModal />
61
71
  </FontdueProvider>
62
72
  </body>
@@ -65,183 +75,542 @@ export default async function RootLayout({
65
75
  }
66
76
  ```
67
77
 
68
- For details on integrating into your Next.js app, read our [Next.js guide](https://docs.fontdue.com/nextjs)
78
+ ```tsx
79
+ // app/fonts/[slug]/page.tsx — no explicit preload needed.
80
+ import TypeTester from "fontdue-js/TypeTester";
69
81
 
70
- ## IDs
82
+ export default function FontPage() {
83
+ return <TypeTester familyName="Example" styleName="Regular" />;
84
+ }
85
+ ```
86
+
87
+ Example repo: [`fontdue/fontdue-example-next`](https://github.com/fontdue/fontdue-example-next)
88
+
89
+ </details>
71
90
 
72
- ⚠️ Some components accept a `collectionId` prop. Note this is the `id` returned from the [GraphQL API](https://docs.fontdue.com/graphql-api).
91
+ <details>
92
+ <summary><b>Astro</b></summary>
73
93
 
74
- You may alternatively specify a `collectionSlug` for these components, which can be useful if you are not consuming the GraphQL API. However, we recommend using `collectionId` when possible.
94
+ Add the Vite plugin to `astro.config.mjs`:
95
+
96
+ ```ts
97
+ import { defineConfig } from "astro/config";
98
+ import react from "@astrojs/react";
99
+ import fontdueJs from "fontdue-js/vite";
100
+
101
+ export default defineConfig({
102
+ integrations: [react()],
103
+ vite: { plugins: [fontdueJs()] },
104
+ });
105
+ ```
106
+
107
+ In Astro, every `client:*` component is its own React island — `<FontdueProvider>` doesn't form a React parent of your page components. Instead, it's a sibling island that sets up Fontdue's core on your site. Per-page components (`<TypeTester>`, etc.) self-wrap their own context when no parent provider is in scope.
108
+
109
+ ```astro
110
+ ---
111
+ // src/layouts/Layout.astro
112
+ import FontdueProvider, { loadFontdueProviderQuery } from "fontdue-js/FontdueProvider";
113
+ import StoreModal from "fontdue-js/StoreModal";
114
+ import "fontdue-js/fontdue.css";
115
+
116
+ const fontduePreload = await loadFontdueProviderQuery();
117
+ ---
118
+
119
+ <html lang="en">
120
+ <body>
121
+ <FontdueProvider client:load preloadedQuery={fontduePreload} />
122
+ <StoreModal client:load />
123
+ <slot />
124
+ </body>
125
+ </html>
126
+ ```
127
+
128
+ Per-page preload runs in frontmatter:
129
+
130
+ ```astro
131
+ ---
132
+ // src/pages/fonts/[slug].astro
133
+ import Layout from "../../layouts/Layout.astro";
134
+ import TypeTester, { loadTypeTesterQuery } from "fontdue-js/TypeTester";
135
+
136
+ const preloaded = await loadTypeTesterQuery({
137
+ familyName: "Example",
138
+ styleName: "Regular",
139
+ });
140
+ ---
141
+
142
+ <Layout>
143
+ <TypeTester client:load preloadedQuery={preloaded} content="The quick brown fox" fontSize={64} />
144
+ </Layout>
145
+ ```
146
+
147
+ Example repo: [`fontdue/example-astro`](https://github.com/fontdue/example-astro)
148
+
149
+ </details>
150
+
151
+ <details>
152
+ <summary><b>React Router 7</b></summary>
153
+
154
+ Add the Vite plugin to `vite.config.ts`:
155
+
156
+ ```ts
157
+ import { defineConfig } from "vite";
158
+ import { reactRouter } from "@react-router/dev/vite";
159
+ import fontdueJs from "fontdue-js/vite";
160
+
161
+ export default defineConfig({
162
+ plugins: [reactRouter(), fontdueJs()],
163
+ });
164
+ ```
165
+
166
+ Preload in the root route's loader, pass the result through `loaderData`:
167
+
168
+ ```tsx
169
+ // app/root.tsx
170
+ import { Outlet } from "react-router";
171
+ import FontdueProvider, { loadFontdueProviderQuery } from "fontdue-js/FontdueProvider";
172
+ import StoreModal from "fontdue-js/StoreModal";
173
+ import "fontdue-js/fontdue.css";
174
+ import type { Route } from "./+types/root";
175
+
176
+ export async function loader() {
177
+ return { fontduePreload: await loadFontdueProviderQuery() };
178
+ }
179
+
180
+ export default function App({ loaderData }: Route.ComponentProps) {
181
+ return (
182
+ <FontdueProvider preloadedQuery={loaderData.fontduePreload}>
183
+ <Outlet />
184
+ <StoreModal />
185
+ </FontdueProvider>
186
+ );
187
+ }
188
+ ```
189
+
190
+ Per-page preload mirrors the same shape:
191
+
192
+ ```tsx
193
+ // app/routes/fonts.$slug.tsx
194
+ import TypeTester, { loadTypeTesterQuery } from "fontdue-js/TypeTester";
195
+
196
+ export async function loader() {
197
+ return {
198
+ preloadedQuery: await loadTypeTesterQuery({
199
+ familyName: "Example",
200
+ styleName: "Regular",
201
+ }),
202
+ };
203
+ }
204
+
205
+ export default function FontPage({ loaderData }) {
206
+ return <TypeTester preloadedQuery={loaderData.preloadedQuery} content="…" fontSize={64} />;
207
+ }
208
+ ```
209
+
210
+ Example repo: [`fontdue/example-react-router`](https://github.com/fontdue/example-react-router)
211
+
212
+ </details>
213
+
214
+ <details>
215
+ <summary><b>TanStack Start</b></summary>
216
+
217
+ Add the Vite plugin to `vite.config.ts` (alongside TanStack's plugin). Preload in the root route's `loader`:
218
+
219
+ ```tsx
220
+ // src/routes/__root.tsx
221
+ import { Outlet, createRootRoute } from "@tanstack/react-router";
222
+ import FontdueProvider, { loadFontdueProviderQuery } from "fontdue-js/FontdueProvider";
223
+ import StoreModal from "fontdue-js/StoreModal";
224
+ import "fontdue-js/fontdue.css";
225
+
226
+ export const Route = createRootRoute({
227
+ loader: async () => ({ fontduePreload: await loadFontdueProviderQuery() }),
228
+ component: RootComponent,
229
+ });
230
+
231
+ function RootComponent() {
232
+ const { fontduePreload } = Route.useLoaderData();
233
+ return (
234
+ <FontdueProvider preloadedQuery={fontduePreload}>
235
+ <Outlet />
236
+ <StoreModal />
237
+ </FontdueProvider>
238
+ );
239
+ }
240
+ ```
241
+
242
+ Per-page preload uses each route's `loader`:
243
+
244
+ ```tsx
245
+ // src/routes/fonts.$slug.tsx
246
+ import { createFileRoute } from "@tanstack/react-router";
247
+ import TypeTester, { loadTypeTesterQuery } from "fontdue-js/TypeTester";
248
+
249
+ export const Route = createFileRoute("/fonts/$slug")({
250
+ loader: async () => ({
251
+ preloadedQuery: await loadTypeTesterQuery({
252
+ familyName: "Example",
253
+ styleName: "Regular",
254
+ }),
255
+ }),
256
+ component: FontPage,
257
+ });
258
+
259
+ function FontPage() {
260
+ const { preloadedQuery } = Route.useLoaderData();
261
+ return <TypeTester preloadedQuery={preloadedQuery} content="…" fontSize={64} />;
262
+ }
263
+ ```
264
+
265
+ Example repo: [`fontdue/example-tanstack`](https://github.com/fontdue/example-tanstack)
266
+
267
+ </details>
268
+
269
+ <details>
270
+ <summary><b>Other Vite-based frameworks (Vike, Remix, plain Vite SSR)</b></summary>
271
+
272
+ Add `fontdueJs()` to your Vite plugins. Run `loadFontdueProviderQuery()` wherever your framework loads layout-level data (Vike's `+data.ts`, Remix's root `loader`, etc.) and pass the result to `<FontdueProvider preloadedQuery>`. The component-level `load*Query()` helpers work the same way for per-page data.
273
+
274
+ Vike example — `+data.ts` for the layout, plus a per-page data loader. Re-export `Data = Awaited<ReturnType<typeof data>>` from each `+data.ts` so `useData<Data>()` gets a proper type without restating the shape:
275
+
276
+ ```ts
277
+ // pages/+data.ts
278
+ import { loadFontdueProviderQuery } from "fontdue-js/FontdueProvider";
279
+
280
+ export const data = async () => ({
281
+ fontduePreload: await loadFontdueProviderQuery(),
282
+ });
283
+ export type Data = Awaited<ReturnType<typeof data>>;
284
+ ```
285
+
286
+ ```tsx
287
+ // pages/+Layout.tsx
288
+ import { useData } from "vike-react/useData";
289
+ import FontdueProvider from "fontdue-js/FontdueProvider";
290
+ import StoreModal from "fontdue-js/StoreModal";
291
+ import "fontdue-js/fontdue.css";
292
+ import type { Data } from "./+data";
293
+
294
+ export default function Layout({ children }: { children: React.ReactNode }) {
295
+ const { fontduePreload } = useData<Data>();
296
+ return (
297
+ <FontdueProvider preloadedQuery={fontduePreload}>
298
+ {children}
299
+ <StoreModal />
300
+ </FontdueProvider>
301
+ );
302
+ }
303
+ ```
304
+
305
+ ```ts
306
+ // pages/fonts/@slug/+data.ts
307
+ import { loadTypeTesterQuery } from "fontdue-js/TypeTester";
308
+
309
+ export const data = async () => ({
310
+ preloadedQuery: await loadTypeTesterQuery({
311
+ familyName: "Example",
312
+ styleName: "Regular",
313
+ }),
314
+ });
315
+ export type Data = Awaited<ReturnType<typeof data>>;
316
+ ```
317
+
318
+ ```tsx
319
+ // pages/fonts/@slug/+Page.tsx
320
+ import { useData } from "vike-react/useData";
321
+ import TypeTester from "fontdue-js/TypeTester";
322
+ import type { Data } from "./+data";
323
+
324
+ export default function FontPage() {
325
+ const { preloadedQuery } = useData<Data>();
326
+ return <TypeTester preloadedQuery={preloadedQuery} content="…" fontSize={64} />;
327
+ }
328
+ ```
329
+
330
+ Remix follows the same shape with root `loader` / route `loader` + `useLoaderData()`. We don't ship an example repo for these yet — open an issue if you'd like one.
331
+
332
+ </details>
333
+
334
+ <details>
335
+ <summary><b>Client-only / no SSR</b></summary>
336
+
337
+ Mount `<FontdueProvider>` (no `preloadedQuery`) and render components with their lazy props (`{collectionId}`, `{familyName, styleName}`, etc.). They fetch on mount.
338
+
339
+ ```tsx
340
+ import FontdueProvider from "fontdue-js/FontdueProvider";
341
+ import StoreModal from "fontdue-js/StoreModal";
342
+ import TypeTester from "fontdue-js/TypeTester";
343
+ import "fontdue-js/fontdue.css";
344
+
345
+ export default function App() {
346
+ return (
347
+ <FontdueProvider>
348
+ <TypeTester familyName="Example" styleName="Regular" />
349
+ <StoreModal />
350
+ </FontdueProvider>
351
+ );
352
+ }
353
+ ```
354
+
355
+ </details>
356
+
357
+ ## IDs
358
+
359
+ > Some components accept a `collectionId`. This is the `id` returned from the [GraphQL API](https://docs.fontdue.com/graphql-api). You can alternatively pass `collectionSlug`, which is useful when you aren't consuming the GraphQL API directly. Prefer `collectionId` when possible.
75
360
 
76
361
  ---
77
362
 
78
363
  # Components
79
364
 
365
+ Every component below has a default export and (where applicable) a `load{Component}Query` named export for the SSR preload path. Both share a single entry point per component.
366
+
367
+ ## Lazy vs. preloaded props
368
+
369
+ Most components accept their data in one of two shapes:
370
+
371
+ - **Lazy props** — the identifying inputs the component needs to look up its own data: `collectionId` / `collectionSlug` for collection-bound components, `familyName` + `styleName` for the standalone `<TypeTester>`, nothing at all for forms like `<NewsletterSignup>` or `<TestFontsForm>`. The component fetches on mount, on the client, and shows nothing in the meantime.
372
+ - **`preloadedQuery`** — the result of calling the corresponding `load{Component}Query(…)` helper on the server. The component skips its own fetch, renders synchronously from the payload, and hydrates on the client without a re-fetch.
373
+
374
+ Both shapes are mutually exclusive on each component. You can mix them across the page — e.g. preload a `<TypeTester>` on a font-detail route while using a lazy `<BuyButton>` on the same page — and you can mix them across pages, since the choice is per-render.
375
+
376
+ ```tsx
377
+ // Lazy — fetches on the client.
378
+ <TypeTester familyName="Example" styleName="Regular" />
379
+
380
+ // Preloaded — server-rendered, hydrates without a fetch.
381
+ const preloadedQuery = await loadTypeTesterQuery({
382
+ familyName: "Example",
383
+ styleName: "Regular",
384
+ });
385
+ <TypeTester preloadedQuery={preloadedQuery} />
386
+ ```
387
+
388
+ **Which to use?**
389
+
390
+ - If you're in Next.js's App Router, use the lazy props — React Server Components takes care of the preload internally for you.
391
+ - If you're in any other framework with SSR (Astro, RR7, TanStack, Vike, Remix), prefer `preloadedQuery`. Otherwise the page hydrates with a flash of empty content while each component fetches.
392
+ - If your site is client-only (no SSR), lazy props are the only option.
393
+
394
+ A few components don't accept `preloadedQuery`:
395
+
396
+ - **`StoreModal`** and **`CartButton`** still render server-side, but without a preloaded query — their fetch always happens on the client after hydration, and the SSR output is the empty Suspense fallback. The reason: their data is per-customer-session (cart contents, modal-open state) and a build-time / CDN-cached SSR call would just cache an empty cart and delay the real one. `<CartButton>` reflects the right count as soon as the post-hydration fetch resolves; `<StoreModal>` renders nothing visible until opened, so there's nothing to flash.
397
+ - **`CustomerLoginForm`** has no preload helper today — it's a thin form with no upfront data needs.
80
398
 
81
399
  ## `FontdueProvider`
82
400
 
83
- The FontdueProvider provides necessary context for all the other Fontdue.js components, so it must be an ancestor of all other components. See example in our [guide](https://docs.fontdue.com/nextjs).
401
+ Provides the Fontdue context (Relay environment, Redux store, config, components map) and renders auxiliary UI (theme, test-mode banner, consent banner, tracking). Render once at the layout level.
84
402
 
85
403
  ```tsx
86
- import FontdueProvider from 'fontdue-js/FontdueProvider';
404
+ import FontdueProvider, { loadFontdueProviderQuery } from "fontdue-js/FontdueProvider";
87
405
  ```
88
406
 
89
407
  | Prop | Description |
90
408
  | --- | --- |
91
- | `url` | `string` Your Fontdue store URL, in the form `https://your-site.fontdue.com`. |
92
- | `config` | `object` Config object. Refer to the [Fontdue.js docs site](https://docs.fontdue.com/fontduejs#b3dec49aa08240bba2b4c71a67c08333) for available config options. |
93
- | `components` | `object` Component view overrides. This API will likely change. |
409
+ | `preloadedQuery` | (Recommended) Result of `loadFontdueProviderQuery()`. Warms aux UI synchronously. |
410
+ | `config` | `object` UI config. See [Fontdue.js config docs](https://docs.fontdue.com/fontduejs#b3dec49aa08240bba2b4c71a67c08333). |
94
411
 
95
412
  ## `StoreModal`
96
413
 
97
- Renders the Fontdue cart + checkout experience as a modal. This appears when a user clicks on a [`BuyButton`](#buybutton) or the buy button within [`TypeTesters`](#typetesters)
414
+ The cart and checkout UI, rendered as a modal. Mount once at the layout level. Opens when a `BuyButton` is clicked or when navigated to from another component.
98
415
 
99
416
  ```tsx
100
- import StoreModal from 'fontdue-js/StoreModal';
417
+ import StoreModal from "fontdue-js/StoreModal";
101
418
  ```
102
419
 
103
- ## `BuyButton`
420
+ `StoreModal` doesn't accept `preloadedQuery` — its content is per-customer-session (cart contents, modal-open state), which isn't safe to resolve at SSR time. The component still renders server-side, but its data fetch always runs on the client after hydration. The modal is closed by default, so there's nothing visible to flash.
104
421
 
105
- A button which when clicked opens the Cart to the relevant collection, and selects the collection.
422
+ ## `BuyButton`
106
423
 
107
- Renders a button with the text `Buy {collectionName}`
424
+ A button that opens `StoreModal` to the relevant collection.
108
425
 
109
426
  ```tsx
110
- import BuyButton from 'fontdue-js/BuyButton';
427
+ import BuyButton, { loadBuyButtonQuery } from "fontdue-js/BuyButton";
111
428
  ```
112
429
 
113
430
  | Prop | Description |
114
431
  | --- | --- |
115
- | `collectionId` or `collectionSlug` | (Required) `string` Collection identifier |
116
- | `collectionName` | (Optional) `string` The name to render in the button: `Buy {collectionName}` |
117
- | `label` | (Optional) `string` Label for the button (defaults to `Buy {collectionName}`) |
432
+ | `collectionId` or `collectionSlug` | (Required, lazy) `string` Collection identifier. Omit if passing `preloadedQuery`. |
433
+ | `preloadedQuery` | (Required, SSR) Result of `loadBuyButtonQuery({ collectionId })` or `loadBuyButtonQuery({ collectionSlug })`. |
434
+ | `collectionName` | (Optional) `string` Name to render in the default label: `Buy {collectionName}`. |
435
+ | `label` | (Optional) `string` Override the button label entirely. |
118
436
 
119
437
  ## `CartButton`
120
438
 
121
- A button to open the Store Modal. If the user has items in their cart, the button will navigate straight to the Cart screen. Otherwise it opens the fonts index.
439
+ Opens `StoreModal`, jumping straight to the cart screen if there are items in it.
122
440
 
123
441
  ```tsx
124
- import CartButton from 'fontdue-js/CartButton';
442
+ import CartButton from "fontdue-js/CartButton";
125
443
  ```
126
444
 
445
+ No `preloadedQuery` (same reason as `StoreModal`). Renders server-side with an empty Suspense fallback, then fetches the cart on the client after hydration and updates with the live count. Render anywhere; safe with or without an explicit `<FontdueProvider>` ancestor.
446
+
127
447
  | Prop | Description |
128
448
  | --- | --- |
129
- | `buttonStyle` | (Optional) `'icon' \| 'inline'` Button style. If left blank, the button is unstyled. |
130
- | `label` | (Optional) `string` For non-icon style buttons, the text to render inside the button. Defaults to "Cart" |
449
+ | `buttonStyle` | (Optional) `string` Pass `'icon'` to render the cart icon instead of a text label. The value is also surfaced as `data-button-style` on the rendered `<button>` so you can target other styles via CSS. |
450
+ | `label` | (Optional) `string` Text content. Defaults to `"Cart"`. Ignored when `buttonStyle="icon"`. |
451
+ | `suffix` | (Optional) `string` Template appended to the label. Substitutions: `{count}`, `{subtotal}`. Hidden when the cart is empty. |
452
+ | `children` | (Optional) `ReactNode` Custom button contents. Replaces the default label / icon entirely. |
131
453
 
132
454
  ## `CharacterViewer`
133
455
 
134
- An interactive character/glyph explorer.
456
+ An interactive character / glyph explorer.
135
457
 
136
458
  ```tsx
137
- import CharacterViewer from 'fontdue-js/CharacterViewer';
459
+ import CharacterViewer, { loadCharacterViewerQuery } from "fontdue-js/CharacterViewer";
138
460
  ```
139
461
 
140
462
  | Prop | Description |
141
463
  | --- | --- |
142
- | `collectionId` or `collectionSlug` | (Required) `string` Identifier for collection |
143
-
464
+ | `collectionId` or `collectionSlug` | (Required, lazy) `string` Collection identifier. |
465
+ | `preloadedQuery` | (Required, SSR) Result of `loadCharacterViewerQuery({ collectionId })` or `loadCharacterViewerQuery({ collectionSlug })`. |
144
466
 
145
467
  ## `CustomerLoginForm`
146
468
 
147
- A form for customers to log in and retrieve their order history. When they enter
148
- their email address, they receive a link to a Fontdue-hosted page to view orders.
469
+ A form for customers to look up their order history. Submitting an email address sends a link to a Fontdue-hosted orders page.
149
470
 
150
471
  ```tsx
151
- import CustomerLoginForm from 'fontdue-js/CustomerLoginForm';
472
+ import CustomerLoginForm from "fontdue-js/CustomerLoginForm";
152
473
  ```
153
474
 
154
475
  | Prop | Description |
155
476
  | --- | --- |
156
- | `submitLabel` | `string` Label for the submit button, defaults to "Submit" |
477
+ | `submitLabel` | (Optional) `string` Submit button label. Defaults to `"Submit"`. |
157
478
 
158
479
  ## `TypeTesters`
159
480
 
160
- A group of type tester components for a collection. You must first add content for the collection's type testers through the Fontdue dashboard.
481
+ Group of type testers configured through the Fontdue dashboard.
161
482
 
162
483
  ```tsx
163
- import TypeTesters from 'fontdue-js/TypeTesters';
484
+ import TypeTesters, { loadTypeTestersQuery } from "fontdue-js/TypeTesters";
164
485
  ```
165
486
 
166
487
  | Prop | Description |
167
488
  | --- | --- |
168
- | `collectionId` or `collectionSlug` | (Required) `string` Identifier for collection |
169
- | `defaultMode` | (Optional) `'local' \| 'global'` The mode refers to the toggle in the UI: Affect all styles. `local` mode has this toggle turned off by default, `global` turns it on |
170
- | `autofit` | (Optional) `boolean` Set to `true` to make the sentences fit on one line. It will adjust to the width of the tester as the user changes their browser window. If the user changes the font size or edits content, autofitting is turned off for that tester |
171
- | `tags` | (Optional) `string[]` Will render only type testers that include any of these tags |
172
- | `excludeTags` | (Optional) `string[]` Will exclude type testers that include any of these tags |
173
- | `onFocus` | (Optional) `() => void` when any type tester is focused |
174
- | `onBlur` | (Optional) `() => void` when any type tester is blurred |
175
- | `onToolbarOpenClose` | (Optional) `(open: boolean) => void` Callback when toolbar is opened/closed |
489
+ | `collectionId` or `collectionSlug` | (Required, lazy) `string` Collection identifier. |
490
+ | `preloadedQuery` | (Required, SSR) Result of `loadTypeTestersQuery({ collectionId, tags?, excludeTags? })` or `loadTypeTestersQuery({ collectionSlug, tags?, excludeTags? })`. |
491
+ | `defaultMode` | (Optional) `'group' \| 'local'` Whether the "Affect all styles" toggle starts on (`group`) or off (`local`). |
492
+ | `autofit` | (Optional) `boolean` Make sentences fit on one line, adjusting size as the container resizes. Disables when the user changes font size or content. |
493
+ | `tags` | (Optional) `string[]` Render only testers tagged with any of these. |
494
+ | `excludeTags` | (Optional) `string[]` Exclude testers tagged with any of these. |
495
+ | `features` | (Optional) `string[]` OpenType feature codes to expose to users across all testers in the group (e.g. `['ss01', 'ss02']`). |
496
+ | `onFocus` | (Optional) `() => void` Fired when any tester gains focus. |
497
+ | `onBlur` | (Optional) `() => void` Fired when any tester loses focus. |
498
+ | `onToolbarOpenClose` | (Optional) `(open: boolean) => void` Fired when the toolbar opens or closes. |
176
499
 
177
500
  ## `TypeTester` (standalone)
178
501
 
179
- Standalone version of the type tester, which does not query the Fontdue CMS for content. You supply the content instead. Does not support the "Affect all styles" feature of the TypeTesters component.
502
+ Standalone tester driven by props rather than dashboard content. Doesn't support the "Affect all styles" toggle.
180
503
 
181
504
  ```tsx
182
- import TypeTester from 'fontdue-js/TypeTester';
505
+ import TypeTester, { loadTypeTesterQuery } from "fontdue-js/TypeTester";
183
506
  ```
184
507
 
185
508
  | Prop | Description |
186
509
  | --- | --- |
187
- | `familyName` | (Required) `string` Font family name (must have been already uploaded to your Fontdue admin) |
188
- | `styleName` | (Required) `string` The name of the style from the family to display. |
510
+ | `familyName` and `styleName` | (Required, lazy) `string` Identify the font style to render. The family/style must already be uploaded to your Fontdue admin. |
511
+ | `preloadedQuery` | (Required, SSR) Result of `loadTypeTesterQuery({ familyName, styleName })`. |
189
512
  | `fontSize` | (Optional) `number` Initial font size in pixels. |
190
- | `lineHeight` | (Optional) `number` Line-height as a proportional value where `1 == fontSize`. |
191
- | `content` | (Optional) `string` The initial content to display. |
192
- | `direction` | (Optional) `'ltr' \| 'rtl'` Writing direction |
193
- | `alignment` | (Optional) `'left' \| 'center' \| 'right'` Text alignment |
194
- | `features` | (Optional) `string[]` List of opentype feature codes to expose as options to users. (e.g. `['ss01', 'ss02']`) |
195
- | `axes` | (Optional) `string[]` List of variable axes to expose. (e.g. `['wdth', 'ital']`). You must provide the relevant `variableSettings` for each axis |
196
- | `autofit` | (Optional) See `TypeTesters.autofit` above |
197
- | `featureSettings` | (Optional) `{ feature: string, value: string }[]` List of features already selected, the `value` should be `"1"` to mark the feature as selected. The shape of this data is consistent with the `TypeTester.featureSettings` field in the GraphQL API. e.g. `[{ feature: 'ss01', value: '1' }]` |
198
- | `variableSettings` | (Optional) `{ axis: string, value: number }[]` List of variable settings selected, consistent with the `TypeTester.variableSettings` field. e.g. `[{ axis: 'wdth', value: 600 }, { axis: 'ital', value: 0.5 }]` |
513
+ | `lineHeight` | (Optional) `number` Proportional line height (`1` == `fontSize`). |
514
+ | `letterSpacing` | (Optional) `number` Letter spacing. |
515
+ | `content` | (Optional) `string` Initial content. |
516
+ | `direction` | (Optional) `'ltr' \| 'rtl'` Writing direction. |
517
+ | `alignment` | (Optional) `'left' \| 'center' \| 'right'` Text alignment. |
518
+ | `features` | (Optional) `string[]` OpenType feature codes to expose to users (e.g. `['ss01', 'ss02']`). |
519
+ | `featuresSelected` | (Optional) `string[]` Subset of `features` to mark as initially selected. |
520
+ | `axes` | (Optional) `string[]` Variable axes to expose (e.g. `['wdth', 'ital']`). Pair with `variableSettings`. |
521
+ | `featureSettings` | (Optional) `{ feature: string, value: string }[]` Pre-selected features. Shape matches `TypeTester.featureSettings` in the GraphQL API. |
522
+ | `variableSettings` | (Optional) `{ axis: string, value: number }[]` Pre-selected axis values. Shape matches `TypeTester.variableSettings` in the GraphQL API. |
523
+ | `autofit` | (Optional) See `TypeTesters.autofit` above. |
524
+ | `onFocus` / `onBlur` | (Optional) `() => void` |
199
525
 
200
526
  ## `TestFontsForm`
201
527
 
202
- Displays a form for users to enter their information and download test fonts. Make sure you have configured [Test Fonts](https://docs.fontdue.com/test-fonts) for this to work.
528
+ A form that lets visitors download test fonts after entering their details. Requires [Test Fonts](https://docs.fontdue.com/test-fonts) to be configured.
203
529
 
204
530
  ```tsx
205
- import TestFontsForm from 'fontdue-js/TestFontsForm';
531
+ import TestFontsForm, { loadTestFontsFormQuery } from "fontdue-js/TestFontsForm";
206
532
  ```
207
533
 
208
534
  | Prop | Description |
209
535
  | --- | --- |
210
- | `agreementLabel` | (Optional) `string` Label for required checkbox. Defaults to the field "EULA agreement text" in your Fontdue Labels settings |
211
- | `downloadLabel` | (Optional) `string` Download button label. Defaults to "Download test fonts" |
212
- | `newsletterCheckboxChecked` | (Optional) `boolean` Set the newsletter opt-in checkbox checked by default |
536
+ | `preloadedQuery` | (Optional, SSR) Result of `loadTestFontsFormQuery()`. Lazy if omitted. |
537
+ | `agreementLabel` | (Optional) `string` Label for the required agreement checkbox. Defaults to the "EULA agreement text" field in your Fontdue Labels settings. |
538
+ | `downloadLabel` | (Optional) `string` Submit button label. Defaults to `"Download test fonts"`. |
539
+ | `newsletterCheckboxChecked` | (Optional) `boolean` Pre-check the newsletter opt-in. |
213
540
 
214
541
  ## `NewsletterSignup`
215
542
 
216
- A newsletter signup form. Customers entering their information here simply adds them as a Customer in the Fontdue CMS.
543
+ A signup form that adds the visitor as a Customer in Fontdue.
217
544
 
218
545
  ```tsx
219
- import NewsletterSignup from 'fontdue-js/NewsletterSignup';
546
+ import NewsletterSignup, { loadNewsletterSignupQuery } from "fontdue-js/NewsletterSignup";
220
547
  ```
221
548
 
222
549
  | Prop | Description |
223
550
  | --- | --- |
224
- | `optInLabel` | (Required) `string` Label that appears with the checkbox required to be checked. |
225
- | `buttonLabel` | (Optional) `string` Label for the button. Defaults to "Subscribe" |
226
- | `optInCheckboxChecked` | (Optional) `boolean` Set the checkbox checked by default. |
551
+ | `preloadedQuery` | (Optional, SSR) Result of `loadNewsletterSignupQuery()`. Lazy if omitted. |
552
+ | `title` | (Optional) `string` Heading rendered above the form. |
553
+ | `intro` | (Optional) `string` Paragraph rendered between the title and the form. |
554
+ | `optInLabel` | (Optional) `string` Label rendered next to the opt-in checkbox. Defaults to the "Newsletter opt-in label" field in your Fontdue Labels settings. |
555
+ | `buttonLabel` | (Optional) `string` Submit button label. Defaults to `"Subscribe"`. |
556
+ | `successLabel` | (Optional) `string` Message shown after a successful submission. Defaults to the "Newsletter success label" field in your Fontdue Labels settings. |
557
+ | `optInCheckboxChecked` | (Optional) `boolean` Pre-check the opt-in box. |
558
+
559
+ ---
560
+
561
+ # Hooks
227
562
 
228
563
  ## `useFont`
229
564
 
230
- A hook to load and render a web font. Pass `webfontSources` to load fonts directly via the FontFace API (no CSS `@font-face` required). The `webfontSources` data is available from the `FontStyle.webfontSources` field in the GraphQL API.
565
+ Loads and renders a webfont. Pass `webfontSources` (available as `FontStyle.webfontSources` in the GraphQL API) to load via the FontFace API directly — no CSS `@font-face` needed.
231
566
 
232
567
  ```tsx
233
- import useFont from 'fontdue-js/useFont';
568
+ import useFont from "fontdue-js/useFont";
234
569
 
235
570
  const FontStyle = ({ familyName, styleName, webfontSources }) => {
236
571
  const { style, loaded } = useFont({
237
572
  fontFamily: `${familyName} ${styleName}`,
238
573
  webfontSources,
239
574
  });
240
-
241
575
  return <span style={style}>The quick brown fox</span>;
242
576
  };
243
577
  ```
244
578
 
245
- If `webfontSources` is omitted, the hook falls back to detecting fonts loaded by CSS `@font-face` rules.
579
+ If `webfontSources` is omitted, the hook falls back to detecting fonts loaded by your CSS `@font-face` rules.
580
+
581
+ Also available as `fontdue-js/useFontStyle` for backwards compatibility.
582
+
583
+ ## `useConsent`
584
+
585
+ Returns `true` when the visitor has granted consent for a given category. Re-renders when the consent state changes (e.g. the visitor accepts the consent banner).
586
+
587
+ ```tsx
588
+ import { useConsent } from "fontdue-js/useConsent";
589
+
590
+ const analyticsConsent = useConsent("analytics");
591
+ ```
592
+
593
+ ## `useAutofit`
594
+
595
+ Measures a string against a container and returns a font size that fits on one line. Used internally by `TypeTester`'s `autofit` prop; exported for custom layouts.
596
+
597
+ ```tsx
598
+ import useAutofit from "fontdue-js/useAutofit";
599
+
600
+ const { ref, fontSize, ready } = useAutofit({
601
+ text: "The quick brown fox",
602
+ fontFamily: "Tonka Regular",
603
+ fontSize: 200,
604
+ });
605
+ ```
606
+
607
+ ---
608
+
609
+ # Examples
610
+
611
+ Working repos for each supported framework, all hitting the same `example.fontdue.xyz` store and exercising every preloadable component:
246
612
 
247
- Also available as `fontdue-js/useFontStyle` for backward compatibility.
613
+ - Next.js — [`fontdue/fontdue-example-next`](https://github.com/fontdue/fontdue-example-next)
614
+ - Astro — [`fontdue/example-astro`](https://github.com/fontdue/example-astro)
615
+ - React Router 7 — [`fontdue/example-react-router`](https://github.com/fontdue/example-react-router)
616
+ - TanStack Start — [`fontdue/example-tanstack`](https://github.com/fontdue/example-tanstack)