Merge pull request #81 from superdoc/feat/superdoc-fonts-package

feat(fonts): @superdoc/fonts package for bundled fonts (SD-3441)

Ported-From-Source-Repo: superdoc/orbit
Ported-From-Source-Commit: 45a456f29763f301ab5c336dd26c6f08124c5288
Ported-Public-Prefix: superdoc/public

Author: caio-pizzol

apps/docs/getting-started/fonts.mdx

@@ -6,19 +6,66 @@ keywords: 'fonts, font loading, calibri, cambria, aptos, font fallback, custom f
 
 SuperDoc keeps the font name from the Word document. When SuperDoc ships an approved fallback for that font, it renders with the fallback but keeps the original name for export. When no fallback is available, load the real font in your app.
 
-## Load fonts in your app
+## Bundled fallback fonts
 
-Fonts are your host page's responsibility. `@font-face`, a hosted stylesheet, or a font CDN: anything the browser can resolve.
+A Word document asks for fonts like Calibri, Cambria, and Times New Roman. Most are proprietary, or not installed on every machine. SuperDoc renders them with reviewed open substitutes that match the metrics: Carlito for Calibri, Liberation Serif for Times New Roman, and more. The original name is kept for export.
+
+These substitutes are real `.woff2` files. The browser fetches them from a URL. Installing SuperDoc from npm puts them in `node_modules`, which does not serve them to the browser. So you tell your app where they live. Pick one path.
+
+### Recommended: the `@superdoc/fonts` package
+
+Install the optional pack and pass it. Your bundler (Vite, Webpack, Next, Nuxt) emits the files and rewrites the URLs. No copy step. No path config.
+
+```bash
+npm install @superdoc/fonts
+```
+
+```js
+import { SuperDoc } from 'superdoc';
+import { superdocFonts } from '@superdoc/fonts';
+
+new SuperDoc({
+  selector: '#editor',
+  document: 'contract.docx',
+  fonts: superdocFonts,
+});
+```
+
+### Alternative: host the files yourself
+
+Serve the `.woff2` from your own path or a CDN, then point SuperDoc at them. The files ship in the package at `node_modules/superdoc/dist/fonts/`.
+
+```js
+new SuperDoc({
+  selector: '#editor',
+  document: 'contract.docx',
+  fonts: { assetBaseUrl: '/fonts/' },
+});
+```
+
+Use `fonts.resolveAssetUrl` instead for signed or versioned URLs.
+
+### CDN script build
+
+The CDN build loads the fonts from a path relative to the script. Loading from a public CDN (jsDelivr or unpkg) needs no setup: the fonts resolve to `superdoc@<version>/dist/fonts/...` automatically. If you self-host `superdoc.min.js`, serve its `dist/fonts/` folder beside it.
+
+### Skipping the pack
+
+The pack is optional. Skip it if you load your own fonts for every family, or only need fonts the user's OS already has. When the bundled `.woff2` cannot be fetched, SuperDoc logs a one-time warning and falls back to the original font name. On a machine without that font, the text renders in a system fallback, so it can look unchanged.
+
+## Load your own fonts
+
+For a brand font, a licensed font, or any family SuperDoc does not ship a fallback for, load the real file yourself. Use `@font-face`, a hosted stylesheet, or a font CDN. Anything the browser can resolve.
 
 ```css
 @font-face {
-  font-family: 'Calibri';
-  src: url('/fonts/Carlito-Regular.woff2') format('woff2');
+  font-family: 'Inter';
+  src: url('/fonts/Inter-Regular.woff2') format('woff2');
   font-display: swap;
 }
 ```
 
-For custom or licensed fonts, load the real file yourself. SuperDoc's built-in fallbacks cover only the fonts it ships and verifies.
+SuperDoc's built-in fallbacks cover only the fonts it ships and verifies. For everything else, the real file is yours to provide. To register it through SuperDoc instead of CSS, pass it in `fonts.families` (which composes with `@superdoc/fonts`).
 
 ## Toolbar font list
 

apps/docs/getting-started/frameworks/angular.mdx

@@ -11,14 +11,15 @@ Requires Angular 17.2+. `viewChild()` and `input()` are stable from Angular 19;
 ## Install
 
 ```bash
-npm install superdoc
+npm install superdoc @superdoc/fonts
 ```
 
 ## Basic setup
 
 ```typescript
 import { Component, ElementRef, viewChild, AfterViewInit, inject, DestroyRef } from '@angular/core';
 import { SuperDoc } from 'superdoc';
+import { superdocFonts } from '@superdoc/fonts';
 import 'superdoc/style.css';
 
 @Component({
@@ -38,6 +39,7 @@ export class EditorComponent implements AfterViewInit {
       selector: this.editorRef().nativeElement,
       document: 'contract.docx',
       documentMode: 'editing',
+      fonts: superdocFonts,
     });
   }
 }

apps/docs/getting-started/frameworks/laravel.mdx

@@ -11,6 +11,7 @@ SuperDoc works with Laravel + Blade + Vite. Laravel serves the Blade template wi
 ```bash
 composer install
 npm install
+npm install superdoc @superdoc/fonts
 ```
 
 ## Vite config
@@ -55,9 +56,10 @@ Create a Blade view that loads the Vite-bundled script and mounts the editor:
 
 ```js resources/js/app.js
 import { SuperDoc } from 'superdoc';
+import { superdocFonts } from '@superdoc/fonts';
 import 'superdoc/style.css';
 
-let superdoc = new SuperDoc({ selector: '#editor' });
+let superdoc = new SuperDoc({ selector: '#editor', fonts: superdocFonts });
 
 document.getElementById('file-input').addEventListener('change', (e) => {
     const file = e.target.files[0];

apps/docs/getting-started/frameworks/nextjs.mdx

@@ -10,7 +10,7 @@ SuperDoc works seamlessly with Next.js. The recommended approach is using `@supe
 The React wrapper is the simplest way to integrate SuperDoc with Next.js:
 
 ```bash
-npm install @superdoc-dev/react
+npm install @superdoc-dev/react @superdoc/fonts
 ```
 
 ### App Router (Next.js 13+)
@@ -20,12 +20,14 @@ npm install @superdoc-dev/react
 'use client';
 
 import { SuperDocEditor } from '@superdoc-dev/react';
+import { superdocFonts } from '@superdoc/fonts';
 import '@superdoc-dev/react/style.css';
 
 export default function EditorPage() {
   return (
     <SuperDocEditor
       document="/sample.docx"
+      fonts={superdocFonts}
       documentMode="editing"
       onReady={() => console.log('Editor ready!')}
       style={{ height: '100vh' }}

apps/docs/getting-started/frameworks/nuxt.mdx

@@ -9,7 +9,7 @@ SuperDoc works with Nuxt 4+ as a client-side Vue component. Set `ssr: false` in
 ## Install
 
 ```bash
-npm install superdoc
+npm install superdoc @superdoc/fonts
 ```
 
 ## Configure Nuxt
@@ -33,6 +33,7 @@ Nuxt auto-imports Vue's `ref`, `watch`, and lifecycle hooks: no manual imports n
 ```vue app/pages/index.vue
 <script setup lang="ts">
 import { SuperDoc } from 'superdoc';
+import { superdocFonts } from '@superdoc/fonts';
 
 const container = ref<HTMLDivElement | null>(null);
 const file = ref<File | null>(null);
@@ -50,6 +51,7 @@ const initEditor = () => {
   superdoc = new SuperDoc({
     selector: container.value,
     document: file.value,
+    fonts: superdocFonts,
   });
 };
 

apps/docs/getting-started/frameworks/react.mdx

@@ -9,7 +9,7 @@ SuperDoc provides `@superdoc-dev/react`: a first-party wrapper with lifecycle ma
 ## Install
 
 ```bash
-npm install @superdoc-dev/react
+npm install @superdoc-dev/react @superdoc/fonts
 ```
 
 <Note>
@@ -20,12 +20,14 @@ npm install @superdoc-dev/react
 
 ```jsx
 import { SuperDocEditor } from '@superdoc-dev/react';
+import { superdocFonts } from '@superdoc/fonts';
 import '@superdoc-dev/react/style.css';
 
 function App() {
   return (
     <SuperDocEditor
       document={file}
+      fonts={superdocFonts}
       documentMode="editing"
       onReady={() => console.log('Editor ready!')}
     />

apps/docs/getting-started/frameworks/solid.mdx

@@ -13,14 +13,15 @@ SuperDoc does not ship a first-party Solid wrapper. Use the core `superdoc` pack
 ## Install
 
 ```bash
-npm install superdoc
+npm install superdoc @superdoc/fonts
 ```
 
 ## Quick start
 
 ```tsx
 import { onCleanup, onMount } from 'solid-js';
 import { SuperDoc } from 'superdoc';
+import { superdocFonts } from '@superdoc/fonts';
 import 'superdoc/style.css';
 
 export default function App() {
@@ -30,6 +31,7 @@ export default function App() {
   onMount(() => {
     superdoc = new SuperDoc({
       selector: `#${editorId}`,
+      fonts: superdocFonts,
     });
   });
 

apps/docs/getting-started/frameworks/vanilla-js.mdx

@@ -34,11 +34,13 @@ SuperDoc works with plain JavaScript. No framework required.
 
 ```javascript NPM/Bundler
 import { SuperDoc } from 'superdoc';
+import { superdocFonts } from '@superdoc/fonts';
 import 'superdoc/style.css';
 
 const superdoc = new SuperDoc({
   selector: '#editor',
-  document: 'contract.docx'
+  document: 'contract.docx',
+  fonts: superdocFonts,
 });
 ```
 

apps/docs/getting-started/frameworks/vue.mdx

@@ -8,7 +8,7 @@ SuperDoc works with Vue 3.0+ using Composition API, Options API, or `<script set
 ## Install
 
 ```bash
-npm install superdoc
+npm install superdoc @superdoc/fonts
 ```
 
 ## Basic setup
@@ -23,6 +23,7 @@ npm install superdoc
 <script setup>
 import { ref, onMounted, onBeforeUnmount } from 'vue';
 import { SuperDoc } from 'superdoc';
+import { superdocFonts } from '@superdoc/fonts';
 import 'superdoc/style.css';
 
 const container = ref(null);
@@ -31,7 +32,8 @@ let superdoc = null;
 onMounted(() => {
   superdoc = new SuperDoc({
     selector: container.value,
-    document: 'contract.docx'
+    document: 'contract.docx',
+    fonts: superdocFonts,
   });
 });
 

apps/docs/getting-started/quickstart.mdx

@@ -14,12 +14,12 @@ By the end of this page you'll have a working DOCX editor in your app: load a Wo
 <Tabs>
   <Tab title="npm">
     ```bash
-    npm install superdoc
+    npm install superdoc @superdoc/fonts
     ```
   </Tab>
   <Tab title="React">
     ```bash
-    npm install @superdoc-dev/react
+    npm install @superdoc-dev/react @superdoc/fonts
     ```
   </Tab>
   <Tab title="CDN">
@@ -31,6 +31,10 @@ By the end of this page you'll have a working DOCX editor in your app: load a Wo
   </Tab>
 </Tabs>
 
+<Info>
+  `@superdoc/fonts` serves SuperDoc's bundled fallback fonts so Word fonts render without copying assets. It's optional. See [Font support](/getting-started/fonts).
+</Info>
+
 ## 2. Render the editor
 
 <Tabs>
@@ -40,21 +44,24 @@ By the end of this page you'll have a working DOCX editor in your app: load a Wo
 
     <script type="module">
       import { SuperDoc } from 'superdoc';
+      import { superdocFonts } from '@superdoc/fonts';
       import 'superdoc/style.css';
 
       const superdoc = new SuperDoc({
         selector: '#editor',
+        fonts: superdocFonts,
       });
     </script>
     ```
   </Tab>
   <Tab title="React">
     ```jsx
     import { SuperDocEditor } from '@superdoc-dev/react';
+    import { superdocFonts } from '@superdoc/fonts';
     import '@superdoc-dev/react/style.css';
 
     export default function App() {
-      return <SuperDocEditor />;
+      return <SuperDocEditor fonts={superdocFonts} />;
     }
     ```
   </Tab>