npm package: @flightdev/fonts
Description: Agnostic font optimization with multiple adapter support
Latest version: 0.0.3

# @flightdev/fonts

Font loading and optimization package.

## Installation

```bash
npm install @flightdev/fonts
```

## Quick Start

```typescript
import { createFontLoader } from '@flightdev/fonts';
import { googleFonts } from '@flightdev/fonts/google';

const fonts = createFontLoader({
    adapter: googleFonts(),
});

const inter = await fonts.load('Inter', {
    weight: ['400', '600', '700'],
    subsets: ['latin'],
    display: 'swap',
});

// Use in HTML
document.documentElement.className = inter.className;
```

## Adapters

### Google Fonts

```typescript
import { googleFonts } from '@flightdev/fonts/google';

fonts.load('Roboto', {
    weight: ['400', '700'],
    subsets: ['latin', 'cyrillic'],
});
```

### Local Fonts

```typescript
import { localFonts } from '@flightdev/fonts/local';

const myFont = await fonts.loadLocal('MyFont', {
    src: [
        { path: '/fonts/MyFont-Regular.woff2', weight: '400' },
        { path: '/fonts/MyFont-Bold.woff2', weight: '700' },
    ],
    display: 'swap',
});
```

## React Components

```tsx
import { FontHead } from '@flightdev/fonts/react';

function Layout({ children }) {
    return (
        <html className={inter.className}>
            <head>
                <FontHead fonts={[inter]} />
            </head>
            <body>{children}</body>
        </html>
    );
}
```

## Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `weight` | `string \| string[]` | `'400'` | Font weights |
| `subsets` | `string[]` | `['latin']` | Character subsets |
| `display` | `string` | `'swap'` | font-display value |
| `preload` | `boolean` | `true` | Preload font files |
| `fallback` | `string[]` | `['system-ui']` | Fallback fonts |

## Build-Time Optimization (Vite Plugin)

For optimal performance, use the Vite plugin to automatically optimize fonts during build:

```typescript
// vite.config.ts
import { fontOptimization } from '@flightdev/fonts/vite';

export default defineConfig({
    plugins: [
        fontOptimization({
            // Strategy for subsetting
            strategy: 'named-subsets', // 'used-chars' | 'named-subsets' | 'none'
            
            // Subsets to include (when strategy is 'named-subsets')
            subsets: ['latin', 'latin-ext'],
            
            // Self-host fonts instead of CDN
            selfHost: true,
            
            // Directories to scan for used characters
            scanDirs: ['src'],
        }),
    ],
});
```

### Strategies

| Strategy | Description | Use Case |
|----------|-------------|----------|
| `used-chars` | Scan source files for characters actually used | Smallest fonts, longer build |
| `named-subsets` | Use predefined unicode ranges | Balanced (recommended) |
| `none` | No subsetting | Fastest build |

## Subset Utilities

For manual font optimization:

```typescript
import {
    UNICODE_RANGES,
    extractCharsFromText,
    codePointsToUnicodeRange,
    detectRequiredSubsets,
    generateFontFaceCSS,
} from '@flightdev/fonts/subset';

// Get predefined ranges
const latinRange = UNICODE_RANGES.latin;

// Extract characters from your content
const chars = extractCharsFromText('Hello World!');

// Detect which subsets are needed
const neededSubsets = detectRequiredSubsets(chars);
// ['latin']

// Generate CSS
const css = generateFontFaceCSS('Inter', '/fonts/inter.woff2', {
    weight: '400',
    unicodeRange: latinRange.range,
});
```

### Available Subsets

- `latin`, `latin-ext`
- `cyrillic`, `cyrillic-ext`
- `greek`, `greek-ext`
- `vietnamese`
- `arabic`, `hebrew`, `devanagari`, `thai`
- `japanese`, `korean`, `chinese-simplified`

## License

MIT