fontdue-js 3.0.0-alpha8 → 3.0.0

package/dist/scripts/publishUnicodeData.js

@@ -0,0 +1,68 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DATA_DIR = path.join(__dirname, '../data');
+
+// CDN buckets that serve the unicode-names asset. Both the npm package and the
+// script-tag bundle default to cdn.fontdue.com (prod), so prod is the only
+// strictly-required one — but the asset is reference data, not code, and we
+// push to all three so dev/staging (and any `cdnUrl` override used for testing)
+// resolve too. See docs/GCS.md.
+const BUCKETS = ['fontdue-dev', 'fontdue-staging', 'fontdue-prod'];
+const CACHE_CONTROL = 'public, max-age=31536000, immutable';
+
+// Read the content hash written into unicodeNamesVersion.ts. It's the single
+// source of truth for both the CDN filename and the runtime fetch URL, so the
+// uploaded object always matches what CharacterViewer requests.
+export function readUnicodeNamesVersion() {
+  const src = readFileSync(path.join(DATA_DIR, 'unicodeNamesVersion.ts'), 'utf-8');
+  const match = src.match(/UNICODE_NAMES_VERSION\s*=\s*['"]([^'"]+)['"]/);
+  if (!match) {
+    throw new Error('Could not read UNICODE_NAMES_VERSION from src/data/unicodeNamesVersion.ts');
+  }
+  return match[1];
+}
+
+// Upload data/unicodeNames.json to each CDN bucket at the immutable,
+// content-hashed path the runtime fetches. `-n` (no-clobber) makes this
+// idempotent: a re-run is a no-op unless the data — and therefore the hash —
+// changed. Requires gsutil on PATH and credentials with write access to the
+// buckets (`gcloud auth login`). Throws on failure so the caller can decide
+// whether that's fatal.
+export function publishUnicodeData() {
+  let {
+    buckets = BUCKETS
+  } = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  const version = readUnicodeNamesVersion();
+  const source = path.join(DATA_DIR, 'unicodeNames.json');
+  const fileName = `unicode-names.${version}.json`;
+  for (const bucket of buckets) {
+    const dest = `gs://${bucket}/js/dist/${fileName}`;
+    console.log(`uploading ${fileName} → ${dest}`);
+    execFileSync('gsutil', ['-h', `Cache-Control:${CACHE_CONTROL}`, '-h', 'Content-Type:application/json', 'cp', '-n', '-a', 'public-read', source, dest], {
+      stdio: 'inherit'
+    });
+  }
+  console.log(`unicode names ${version} published to: ${buckets.join(', ')}`);
+}
+
+// A friendly hint for the two failure modes worth distinguishing: gsutil not
+// installed vs. installed-but-can't-write (usually missing auth).
+export function describePublishError(err) {
+  if (err && err.code === 'ENOENT') {
+    return 'gsutil not found on PATH. Install the Google Cloud SDK and authenticate:\n' + '  brew install --cask gcloud-cli   # then restart your shell\n' + '  gcloud auth login\n' + 'See docs/GCS.md.';
+  }
+  return 'Failed to upload to the CDN. Make sure you are authenticated with write\n' + 'access to the buckets:\n' + '  gcloud auth login\n' + 'See docs/GCS.md.';
+}
+
+// CLI entry point: `npm run publish-unicode-data`
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    publishUnicodeData();
+  } catch (err) {
+    console.error(describePublishError(err));
+    process.exit(1);
+  }
+}

package/dist/scripts/updateUnicodeData.js

@@ -1,6 +1,10 @@
-const https = require('https');
-const fs = require('fs');
-const path = require('path');
+import https from 'node:https';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { publishUnicodeData, describePublishError } from './publishUnicodeData.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 // URL from which to fetch the Unicode data
 const UNICODE_DATA_URL = 'https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt';
@@ -31,15 +35,46 @@ function parseAndConvertData(data) {
   return result;
 }
 
-// Main function to fetch, parse, and write the Unicode data to a JSON file
+// Main function to fetch, parse, write, and publish the Unicode data.
+//
+// The map is NOT bundled into the package — it's ~1.2 MB of reference data used
+// only to label glyphs in CharacterViewer. Instead it ships as a static JSON
+// asset served from the Fontdue CDN, which CharacterViewer fetches at runtime.
+// The asset is reference data on its own (roughly yearly) release schedule, so
+// it isn't coupled to the npm publish or the app deploy: regenerating the data
+// here also publishes it to the CDN, and any code that later references the new
+// hash just works.
+//
+// We write two files:
+//   - data/unicodeNames.json        the raw map (uploaded to the CDN; excluded
+//                                   from the npm tarball via .npmignore `src/*`)
+//   - data/unicodeNamesVersion.ts   a content hash of that JSON
+//
+// The hash is the single source of truth for the immutable CDN filename AND the
+// runtime fetch URL, so the two always agree. Refresh = re-run this script.
 async function main() {
   try {
     const data = await fetchUnicodeData();
     const jsonData = parseAndConvertData(data);
-    fs.writeFileSync(path.join(__dirname, '../data/unicodeData.ts'), `const data: { [code: string]: string} = ${JSON.stringify(jsonData)}; export default data;`);
-    console.log('unicode data has been written to unicodeData.ts');
+    const json = JSON.stringify(jsonData);
+    const hash = crypto.createHash('sha256').update(json).digest('hex').slice(0, 16);
+    const dataDir = path.join(__dirname, '../data');
+    fs.writeFileSync(path.join(dataDir, 'unicodeNames.json'), json);
+    fs.writeFileSync(path.join(dataDir, 'unicodeNamesVersion.ts'), `// Generated by \`npm run update-unicode-data\`. Content hash of unicodeNames.json.\n` + `// Both the CDN asset filename and the runtime fetch URL derive from this, so\n` + `// they always agree. Do not edit by hand.\n` + `export const UNICODE_NAMES_VERSION = ${JSON.stringify(hash)};\n`);
+    console.log(`unicode data written: ${Object.keys(jsonData).length} entries, hash ${hash}`);
+
+    // Publish the freshly-written map to the CDN. If this fails (no gsutil /
+    // credentials), don't fail the regen — the data is valid and the hash is
+    // committed; just point the way to publishing it before the change ships.
+    try {
+      publishUnicodeData();
+    } catch (err) {
+      console.warn('\n⚠ Data regenerated, but the CDN upload was skipped or failed. The new\n' + '  hash is in unicodeNamesVersion.ts, but the asset must be on the CDN\n' + '  before any code referencing it ships. Once you have gsutil + creds:\n' + '    npm run publish-unicode-data\n');
+      console.warn(describePublishError(err));
+    }
   } catch (error) {
     console.error('Error:', error);
+    process.exit(1);
   }
 }
 

package/dist/server/index.d.ts

@@ -0,0 +1,37 @@
+export declare class FontdueNotFoundError extends Error {
+    readonly queryName: string;
+    constructor(queryName: string);
+}
+export interface CreateFontdueFetchOptions {
+    /**
+     * GraphQL base URL (without the trailing /graphql), e.g.
+     * https://acme.fontdue.com. Falls back to the per-render config
+     * (resolveFontdueServerConfig().url, set by the Next adapter for the current
+     * tenant) and then to FONTDUE_URL / PUBLIC_FONTDUE_URL / VITE_FONTDUE_URL
+     * from the environment.
+     */
+    url?: string;
+    /**
+     * Extra headers sent with every fetch from this fetcher, merged over the
+     * ambient per-render headers (explicit winning). Pass
+     * `previewAuthHeaders(token)` (from fontdue-js/preview) to reveal hidden
+     * fonts while an admin is in preview.
+     */
+    headers?: Record<string, string>;
+    /**
+    * Next.js data-cache tags. When present — passed here or via the per-render
+    * config — the fetch is opted into Next's data cache so the revalidate
+    * handler can purge it. The global `graphql` tag is always included (and
+    * deduped), so pass the per-site tags alone or the full `endpoint.tags`.
+    * Omit (or pass `[]`) to leave the fetch uncached, which is what preview
+    * renders want. Inert outside Next.
+    */
+    cacheTags?: string[];
+}
+export type FontdueFetch = <Q, V = void>(queryName: string, query: string, variables?: V) => Promise<Q>;
+/**
+ * Build a server-side GraphQL fetcher bound to a base URL and a set of headers.
+ * The returned function takes the operation name, the query text (load it from
+ * your .graphql files), and variables, and resolves to the unwrapped `data`.
+ */
+export declare function createFontdueFetch(options?: CreateFontdueFetchOptions): FontdueFetch;

package/dist/server/index.js

@@ -0,0 +1,160 @@
+// Server-side GraphQL transport for host apps.
+//
+// Every framework example ships a near-identical `fetchGraphql` — resolve the
+// Fontdue URL, POST the query, unwrap `data`, throw on errors. This exports
+// that transport once so apps don't re-implement it, so the preview
+// Authorization header is forwarded in one place, and so the same fetcher
+// works in every server runtime. It is the sibling of the Relay network layer
+// (relay/environment.ts) that powers the embedded components: both read the
+// per-render config from resolveFontdueServerConfig() and apply it the same way.
+//
+// All three per-request inputs — the base URL, the admin preview token, and
+// the Next cache tags — are resolved per call from two sources, so a single
+// module-level fetcher serves every render:
+//
+//   1. Ambient context (preferred): whatever set the per-render config.
+//      - Astro / React Router etc.: runWithPreview (fontdue-js/preview/server)
+//        rides the token through AsyncLocalStorage.
+//      - Next: the single-tenant ambient resolver (registered by mounting
+//        <FontdueProvider>, no per-render call) or __prepareFontdueRender
+//        (fontdue-js/next, multi-tenant) supply the site URL, cache tags, and
+//        preview token for the render.
+//      Either way:
+//
+//        const fetchGraphql = createFontdueFetch();           // once, at module scope
+//        const data = await fetchGraphql('Index', indexQuery, vars);
+//
+//   2. Explicit options: bind a fetcher with a url/headers/cacheTags, for
+//      runtimes where the ambient context can't propagate (route handlers,
+//      Astro edgeMiddleware — see runWithPreview's notes):
+//
+//        const fetchGraphql = createFontdueFetch({
+//          url: endpoint.origin,
+//          headers: previewAuthHeaders(token),                // from fontdue-js/preview
+//          cacheTags: [`graphql:${endpoint.domain}`],
+//        });
+//
+// Explicit options override the ambient context (headers merge, explicit
+// winning), so the two compose.
+//
+// Caching: when the resolved config carries cacheTags (the Next adapter sets
+// them per render; supply them explicitly elsewhere) the fetch is opted into
+// Next's data cache (`force-cache` + tags) so /api/revalidate can purge it.
+// With no tags the fetch is left uncached, which is what preview renders and
+// the CDN-cached frameworks (Astro/RR7 cache HTML at the response layer) want.
+// The Next fetch hints are inert in other runtimes: Node's fetch accepts and
+// ignores the cache mode, and `next` is just an unknown init property.
+
+import { resolveFontdueServerConfig } from '../relay/serverConfig.js';
+import { PREVIEW_HEADER } from '../preview/constants.js';
+function readEnv(name) {
+  if (typeof process !== 'undefined' && process.env) {
+    const v = process.env[name];
+    if (v != null && v !== '') return v;
+  }
+  try {
+    // @ts-ignore - import.meta.env is Vite/Astro-specific
+    const metaEnv = typeof import.meta !== 'undefined' ? import.meta.env : undefined;
+    if (metaEnv) {
+      const v = metaEnv[name] ?? metaEnv[`PUBLIC_${name}`] ?? metaEnv[`VITE_${name}`];
+      if (v != null && v !== '') return v;
+    }
+  } catch {}
+  return undefined;
+}
+function resolveFontdueUrl() {
+  return readEnv('FONTDUE_URL') ?? readEnv('NEXT_PUBLIC_FONTDUE_URL');
+}
+
+// Storefront fetches join Next's data cache only in production. In local dev
+// (`next dev`) that cache plus on-demand `revalidateTag` don't reliably
+// refresh — and the storefront proxy strips the browser's `no-cache`, so a
+// hard reload can't bust a stale entry either. Leaving dev fetches uncached
+// makes every render fetch fresh, so admin content changes show on the next
+// reload with no revalidation needed. Inert outside Next. Read per call (not
+// memoized) so the literal `process.env.NODE_ENV` is inlined at build time and
+// tests can stub it; `typeof process` guards non-Node bundles.
+function cacheInProduction() {
+  return typeof process !== 'undefined' && process.env.NODE_ENV === 'production';
+}
+
+// Thrown when the Fontdue server 404s — i.e. the requested host doesn't resolve
+// to a site. Catch it to surface your framework's own not-found response.
+export class FontdueNotFoundError extends Error {
+  constructor(queryName) {
+    super(`Fontdue returned 404 for query "${queryName}"`);
+    this.queryName = queryName;
+    this.name = 'FontdueNotFoundError';
+  }
+}
+/**
+ * Build a server-side GraphQL fetcher bound to a base URL and a set of headers.
+ * The returned function takes the operation name, the query text (load it from
+ * your .graphql files), and variables, and resolves to the unwrapped `data`.
+ */
+export function createFontdueFetch() {
+  let options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return async function fetchGraphql(queryName, query, variables) {
+    var _json$errors, _json$errors$;
+    // Per-render config (a runWithPreview AsyncLocalStorage store, the Next
+    // render-scoped slot, or the Next single-tenant ambient resolver). Awaited
+    // per call so a single module-level fetcher picks up the current request's
+    // tenant URL, preview token, and cache tags.
+    const config = await resolveFontdueServerConfig();
+
+    // URL: explicit option, then the per-render tenant URL, then the env.
+    const base = options.url ?? (config === null || config === void 0 ? void 0 : config.url) ?? resolveFontdueUrl();
+    if (!base) {
+      throw new Error('fontdue-js: no Fontdue URL configured. Set FONTDUE_URL / ' + 'PUBLIC_FONTDUE_URL / VITE_FONTDUE_URL, pass { url } to ' + 'createFontdueFetch, or set it on the per-render config.');
+    }
+
+    // Cache tags: explicit option wins, else the per-render config's. A
+    // non-empty list opts the fetch into Next's data cache (inert elsewhere);
+    // an empty/absent list leaves it uncached (preview + CDN-cached frameworks).
+    const cacheTags = options.cacheTags ?? (config === null || config === void 0 ? void 0 : config.cacheTags);
+
+    // Ambient headers (e.g. tenant + preview token), overridden by any explicit
+    // per-fetcher headers.
+    const headers = {
+      'content-type': 'application/json',
+      ...(config === null || config === void 0 ? void 0 : config.headers),
+      ...options.headers
+    };
+
+    // Declare preview intent explicitly: a forwarded admin token means this is a
+    // preview render → reveal hidden fonts; otherwise "false" so a public (or
+    // merely session-authenticated) request never gets the hidden-fonts view.
+    // Older clients omit the header and keep the legacy behavior. Mirrors the
+    // Relay network layer (relay/environment.ts) and FontageWeb.Schema.Context.
+    headers[PREVIEW_HEADER] = headers.authorization != null || headers.Authorization != null ? 'true' : 'false';
+
+    // `next` is a Next.js-only fetch extension, ignored by other runtimes.
+    const init = {
+      method: 'POST',
+      body: JSON.stringify({
+        query,
+        variables
+      }),
+      headers
+    };
+    if (cacheInProduction() && Array.isArray(cacheTags) && cacheTags.length > 0) {
+      init.cache = 'force-cache';
+      // The global `graphql` tag is always present; dedupe so callers can pass
+      // the per-site tags alone or the full `endpoint.tags` (which include it).
+      init.next = {
+        tags: Array.from(new Set(['graphql', ...cacheTags]))
+      };
+    }
+    const response = await fetch(`${base}/graphql?query=${queryName}`, init);
+    if (response.status === 404) throw new FontdueNotFoundError(queryName);
+    if (response.status !== 200) {
+      throw new Error(`Fontdue request failed: ${response.status}`);
+    }
+    const json = await response.json();
+    const errorMessage = (_json$errors = json.errors) === null || _json$errors === void 0 ? void 0 : (_json$errors$ = _json$errors[0]) === null || _json$errors$ === void 0 ? void 0 : _json$errors$.message;
+    if (errorMessage) {
+      throw new Error(`Fontdue GraphQL error: ${errorMessage}`);
+    }
+    return json.data;
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fontdue-js",
-  "version": "3.0.0-alpha8",
+  "version": "3.0.0",
   "type": "module",
   "scripts": {
     "build": "npm run relay && run-p build-js build-css build-ts",
@@ -9,6 +9,7 @@
     "build-css": "sass --load-path=node_modules --no-source-map src/index.scss dist/fontdue.css",
     "relay": "relay-compiler",
     "update-unicode-data": "node src/scripts/updateUnicodeData.js",
+    "publish-unicode-data": "node src/scripts/publishUnicodeData.js",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "npm run build"
@@ -82,6 +83,9 @@
   },
   "exports": {
     ".": "./dist/index.js",
+    "./preview": "./dist/preview/index.js",
+    "./preview/server": "./dist/preview/server.js",
+    "./server": "./dist/server/index.js",
     "./next": "./dist/next/index.js",
     "./next/config": "./dist/next/config.js",
     "./next/revalidate": "./dist/next/revalidate.js",

package/types/next-headers.d.ts

@@ -0,0 +1,9 @@
+// Minimal declaration so src/next/tenant.ts type-checks without `next`
+// installed (it's the host app's dependency; this package only ever runs the
+// import inside a Next.js server).
+declare module 'next/headers' {
+  export function draftMode(): Promise<{ isEnabled: boolean }>;
+  export function cookies(): Promise<{
+    get(name: string): { value: string } | undefined;
+  }>;
+}

package/types/next-navigation.d.ts

@@ -0,0 +1,10 @@
+// Minimal declaration so src/next/tenant.ts type-checks without `next`
+// installed (it's the host app's dependency; this package only ever runs the
+// import inside a Next.js server).
+declare module 'next/navigation' {
+  export function notFound(): never;
+  // Re-throws Next's internal control-flow errors (dynamic-rendering bailout,
+  // notFound, redirect) and is a no-op for everything else. Used so the preview
+  // resolver doesn't swallow the bailout that forces a dynamic render.
+  export function unstable_rethrow(error: unknown): void;
+}

package/vitest.config.ts

@@ -2,7 +2,16 @@ import { defineConfig } from 'vitest/config';
 import path from 'path';
 
 export default defineConfig({
+  // Stand-in for the babel define plugin that inlines the package version.
+  define: {
+    __FONTDUE_JS_VERSION__: JSON.stringify('0.0.0-test'),
+  },
   test: {
+    // Only the TypeScript sources are the tests of record. Without this, a
+    // prior `npm run build` leaves compiled copies in dist/__tests__ that
+    // vitest also picks up — running each suite twice and racing on
+    // module-level singletons (e.g. the ambient config resolver).
+    include: ['src/**/*.test.{ts,tsx}'],
     alias: {
       '__generated__': path.resolve(__dirname, 'src/__generated__'),
     },