@symbiote-native/font 0.1.0

package/package.json

@@ -0,0 +1,151 @@
+{
+  "name": "@symbiote-native/font",
+  "version": "0.1.0",
+  "description": "expo-font wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, Svelte, Solid, and Angular adapters. Runtime font loading/unloading by fontFamily, plus a text-to-image render utility.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
+    "directory": "packages/font"
+  },
+  "homepage": "https://github.com/OneEyed1366/symbiote-native/tree/master/packages/font#readme",
+  "bugs": {
+    "url": "https://github.com/OneEyed1366/symbiote-native/issues"
+  },
+  "author": "Andrey Prokopenko <psevdoproger@gmail.com>",
+  "keywords": [
+    "react-native",
+    "symbiote-native",
+    "expo-font",
+    "react",
+    "vue",
+    "svelte",
+    "solid",
+    "angular",
+    "font",
+    "typography"
+  ],
+  "type": "module",
+  "main": "./build/core/index.js",
+  "module": "./build/core/index.js",
+  "types": "./build/core/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./vue": {
+      "types": "./build/vue/index.d.ts",
+      "default": "./build/vue/index.js"
+    },
+    "./react": {
+      "types": "./build/react/index.d.ts",
+      "default": "./build/react/index.js"
+    },
+    "./svelte": {
+      "types": "./build/svelte/index.d.ts",
+      "default": "./build/svelte/index.js"
+    },
+    "./solid": {
+      "types": "./build/solid/index.d.ts",
+      "default": "./build/solid/index.js"
+    },
+    "./angular": {
+      "types": "./build-ngc/angular/index.d.ts",
+      "react-native": "./build-ngc/angular/index.js",
+      "default": "./src/angular/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "build",
+    "build-ngc",
+    "native-link.json",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/*.detox.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "expo-font": "57.0.4",
+    "expo-modules-core": "57.0.20",
+    "@symbiote-native/asset": "0.1.0"
+  },
+  "peerDependencies": {
+    "@angular/core": ">=20",
+    "@vue/runtime-core": "^3.5.13",
+    "react": ">=19.0.0",
+    "react-native": ">=0.86",
+    "solid-js": ">=1.9.0",
+    "svelte": ">=5.56.0",
+    "vue": ">=3.5.0",
+    "@symbiote-native/angular": "^3.1.3",
+    "@symbiote-native/react": "^3.1.0",
+    "@symbiote-native/solid": "^3.0.5",
+    "@symbiote-native/engine": "^1.4.0",
+    "@symbiote-native/vue": "^3.1.0",
+    "@symbiote-native/svelte": "^3.0.5"
+  },
+  "peerDependenciesMeta": {
+    "@symbiote-native/angular": {
+      "optional": true
+    },
+    "@symbiote-native/react": {
+      "optional": true
+    },
+    "@symbiote-native/solid": {
+      "optional": true
+    },
+    "@symbiote-native/svelte": {
+      "optional": true
+    },
+    "@symbiote-native/vue": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "@vue/runtime-core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/compiler": "~22.0.8",
+    "@angular/compiler-cli": "~22.0.8",
+    "@angular/core": "~22.0.8",
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.2.0",
+    "@vue/runtime-core": "^3.5.13",
+    "react": "19.2.3",
+    "solid-js": "^1.9.14",
+    "svelte": "^5.56.0",
+    "typescript": "~6.0.0",
+    "@symbiote-native/svelte": "3.0.5",
+    "@symbiote-native/angular": "3.1.3",
+    "@symbiote-native/react": "3.1.0",
+    "@symbiote-native/engine": "1.4.0",
+    "@symbiote-native/test-utils": "0.4.5",
+    "@symbiote-native/vue": "3.1.0",
+    "@symbiote-native/solid": "3.0.5"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "clean": "rm -rf build-ngc",
+    "ng:build": "pnpm run clean && ngc -p tsconfig.angular.json",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\""
+  }
+}

package/src/angular/index.ts

@@ -0,0 +1,4 @@
+// FontsService is the Angular-only lifecycle half; the loading/caching logic all lives in
+// core, shared with React/Vue/Svelte/Solid.
+export { FontsService } from './services/fonts.service';
+export * from '../core';

package/src/angular/services/fonts.service/index.ts

@@ -0,0 +1,21 @@
+import { Injectable, signal, type Signal } from '@angular/core';
+import { isFontMapLoaded, loadAsync, type FontSource } from '../../../core';
+
+// Angular twin of React's useFonts hook and Vue's useFonts composable — connect(map) returns
+// a Signal pair, e.g. `readonly fonts = inject(FontsService).connect({ Inter: require('...') })`.
+@Injectable({ providedIn: 'root' })
+export class FontsService {
+  connect(map: string | Record<string, FontSource>): {
+    loaded: Signal<boolean>;
+    error: Signal<Error | null>;
+  } {
+    const loaded = signal(isFontMapLoaded(map));
+    const error = signal<Error | null>(null);
+
+    loadAsync(map)
+      .then(() => loaded.set(true))
+      .catch((err: Error) => error.set(err));
+
+    return { loaded: loaded.asReadonly(), error: error.asReadonly() };
+  }
+}

package/src/core/font-loader.ts

@@ -0,0 +1,44 @@
+// Ported from expo-font/src/FontLoader.ts (sdk-57), resolving through @symbiote-native/asset's
+// Asset class (this repo's own expo-asset port) instead of importing expo-asset directly.
+import { Asset } from '@symbiote-native/asset';
+import { CodedError } from 'expo-modules-core';
+
+import { expoFontLoader } from './native-modules';
+import type { FontResource, FontSource } from './types';
+
+export function getAssetForSource(source: FontSource): Asset | FontResource {
+  if (source instanceof Asset) {
+    return source;
+  }
+  if (typeof source === 'string') {
+    return Asset.fromURI(source);
+  }
+  if (typeof source === 'number') {
+    return Asset.fromModule(source);
+  }
+  if (typeof source === 'object' && typeof source.uri !== 'undefined') {
+    return getAssetForSource(source.uri);
+  }
+  return source;
+}
+
+export async function loadSingleFontAsync(
+  name: string,
+  input: Asset | FontResource,
+): Promise<void> {
+  if (!(input instanceof Asset)) {
+    throw new CodedError(
+      'ERR_FONT_SOURCE',
+      '`loadSingleFontAsync` expected a resource of type `Asset` from @symbiote-native/asset',
+    );
+  }
+
+  await input.downloadAsync();
+  if (!input.downloaded || !input.localUri) {
+    throw new CodedError(
+      'ERR_DOWNLOAD',
+      `Failed to download asset for font "${name}"`,
+    );
+  }
+  await expoFontLoader.loadAsync(name, input.localUri);
+}

package/src/core/font-utils.ts

@@ -0,0 +1,39 @@
+// Ported from expo-font/src/FontUtils.ts (sdk-57).
+import { UnavailabilityError } from 'expo-modules-core';
+import { processColor } from 'react-native';
+
+import { expoFontUtils } from './native-modules';
+
+export type IRenderToImageOptions = {
+  fontFamily?: string;
+  size?: number;
+  color?: string;
+  lineHeight?: number;
+};
+
+export type IRenderToImageResult = {
+  uri: string;
+  width: number;
+  height: number;
+  scale: number;
+};
+
+/** @platform android @platform ios */
+export async function renderToImageAsync(
+  glyphs: string,
+  options?: IRenderToImageOptions,
+): Promise<IRenderToImageResult> {
+  if (!expoFontUtils) {
+    throw new UnavailabilityError(
+      'expo-font',
+      'ExpoFontUtils.renderToImageAsync',
+    );
+  }
+
+  return expoFontUtils.renderToImageAsync(glyphs, {
+    ...options,
+    color: options?.color
+      ? (processColor(options.color) ?? undefined)
+      : undefined,
+  });
+}

package/src/core/font.ts

@@ -0,0 +1,150 @@
+// Ported from expo-font/src/Font.ts (sdk-57), native-only — drops the web/server branches
+// (isLoaded's web fallback, loadAsync's server pre-render pass, registerStaticFont).
+import { CodedError, UnavailabilityError } from 'expo-modules-core';
+
+import { getAssetForSource, loadSingleFontAsync } from './font-loader';
+import {
+  isLoadedNative,
+  loadPromises,
+  markLoaded,
+  purgeCache,
+  purgeFontFamilyFromCache,
+} from './memory';
+import { expoFontLoader } from './native-modules';
+import type { FontSource, UnloadFontOptions } from './types';
+
+export function isLoaded(fontFamily: string): boolean {
+  return isLoadedNative(fontFamily);
+}
+
+export function getLoadedFonts(): string[] {
+  return expoFontLoader.getLoadedFonts();
+}
+
+export function isLoading(fontFamily: string): boolean {
+  return fontFamily in loadPromises;
+}
+
+/** Shared seed check for every adapter's `useFonts`/`createFonts` lifecycle wrapper. */
+export function isFontMapLoaded(
+  map: string | Record<string, FontSource>,
+): boolean {
+  if (typeof map === 'string') {
+    return isLoaded(map);
+  }
+  return Object.keys(map).every(fontFamily => isLoaded(fontFamily));
+}
+
+export function loadAsync(
+  fontFamilyOrFontMap: string | Record<string, FontSource>,
+  source?: FontSource,
+): Promise<void> {
+  if (typeof fontFamilyOrFontMap === 'object') {
+    if (source) {
+      return Promise.reject(
+        new CodedError(
+          'ERR_FONT_API',
+          `No fontFamily can be used for the provided source: ${String(source)}. The second argument of loadAsync() can only be used with a string value as the first argument.`,
+        ),
+      );
+    }
+    const fontMap = fontFamilyOrFontMap;
+    const names = Object.keys(fontMap);
+    return Promise.all(
+      names.map(name => loadFontInNamespaceAsync(name, fontMap[name])),
+    ).then(() => {});
+  }
+
+  return loadFontInNamespaceAsync(fontFamilyOrFontMap, source);
+}
+
+async function loadFontInNamespaceAsync(
+  fontFamily: string,
+  source?: FontSource | null,
+): Promise<void> {
+  if (!source) {
+    throw new CodedError(
+      'ERR_FONT_SOURCE',
+      `Cannot load null or undefined font source for fontFamily "${fontFamily}".`,
+    );
+  }
+
+  if (isLoaded(fontFamily)) {
+    return;
+  }
+
+  if (Object.hasOwn(loadPromises, fontFamily)) {
+    return loadPromises[fontFamily];
+  }
+
+  const asset = getAssetForSource(source);
+  loadPromises[fontFamily] = (async () => {
+    try {
+      await loadSingleFontAsync(fontFamily, asset);
+      markLoaded(fontFamily);
+    } finally {
+      delete loadPromises[fontFamily];
+    }
+  })();
+
+  await loadPromises[fontFamily];
+}
+
+/** Always throws on native — ExpoFontLoader has no unload method there, web-only upstream. */
+export async function unloadAllAsync(): Promise<void> {
+  if (!expoFontLoader.unloadAllAsync) {
+    throw new UnavailabilityError('expo-font', 'unloadAllAsync');
+  }
+  if (Object.keys(loadPromises).length) {
+    throw new CodedError(
+      'ERR_UNLOAD',
+      `Cannot unload fonts while they're still loading: ${Object.keys(loadPromises).join(', ')}`,
+    );
+  }
+  purgeCache();
+  await expoFontLoader.unloadAllAsync();
+}
+
+/** Always throws on native — ExpoFontLoader has no unload method there, web-only upstream. */
+export async function unloadAsync(
+  fontFamilyOrFontMap: string | Record<string, UnloadFontOptions>,
+  options?: UnloadFontOptions,
+): Promise<void> {
+  if (!expoFontLoader.unloadAsync) {
+    throw new UnavailabilityError('expo-font', 'unloadAsync');
+  }
+  if (typeof fontFamilyOrFontMap === 'object') {
+    if (options) {
+      throw new CodedError(
+        'ERR_FONT_API',
+        `No fontFamily can be used for the provided options: ${String(options)}. The second argument of unloadAsync() can only be used with a string value as the first argument.`,
+      );
+    }
+    const names = Object.keys(fontFamilyOrFontMap);
+    await Promise.all(
+      names.map(name =>
+        unloadFontInNamespaceAsync(name, fontFamilyOrFontMap[name]),
+      ),
+    );
+    return;
+  }
+  return unloadFontInNamespaceAsync(fontFamilyOrFontMap, options);
+}
+
+async function unloadFontInNamespaceAsync(
+  fontFamily: string,
+  options?: UnloadFontOptions,
+): Promise<void> {
+  if (!isLoaded(fontFamily)) {
+    return;
+  }
+  purgeFontFamilyFromCache(fontFamily);
+
+  if (!fontFamily) {
+    throw new CodedError('ERR_FONT_FAMILY', 'Cannot unload an empty name');
+  }
+  if (!expoFontLoader.unloadAsync) {
+    throw new UnavailabilityError('expo-font', 'unloadAsync');
+  }
+  await expoFontLoader.unloadAsync(fontFamily, options);
+}

package/src/core/index.ts

@@ -0,0 +1,18 @@
+export {
+  isLoaded,
+  getLoadedFonts,
+  isLoading,
+  isFontMapLoaded,
+  loadAsync,
+  unloadAllAsync,
+  unloadAsync,
+} from './font';
+export { renderToImageAsync } from './font-utils';
+export type { IRenderToImageOptions, IRenderToImageResult } from './font-utils';
+export { FontDisplay } from './types';
+export type {
+  FontResource,
+  FontSource,
+  UnloadFontOptions,
+  UseFontsResult,
+} from './types';

package/src/core/memory.ts

@@ -0,0 +1,39 @@
+// Ported verbatim from expo-font/src/memory.ts (sdk-57) — no web/server branch to drop, this
+// module was already native-agnostic.
+import { expoFontLoader } from './native-modules';
+
+export const loadPromises: Record<string, Promise<void>> = {};
+
+let cache: Record<string, boolean> = {};
+
+export function markLoaded(fontFamily: string): void {
+  cache[fontFamily] = true;
+}
+
+export function isLoadedInCache(fontFamily: string): boolean {
+  return fontFamily in cache;
+}
+
+export function isLoadedNative(fontFamily: string): boolean {
+  if (isLoadedInCache(fontFamily)) {
+    return true;
+  }
+
+  const loadedNativeFonts = expoFontLoader.getLoadedFonts();
+  if (!loadedNativeFonts?.length) {
+    return false;
+  }
+
+  loadedNativeFonts.forEach(font => {
+    cache[font] = true;
+  });
+  return fontFamily in cache;
+}
+
+export function purgeFontFamilyFromCache(fontFamily: string): void {
+  delete cache[fontFamily];
+}
+
+export function purgeCache(): void {
+  cache = {};
+}

package/src/core/native-modules.ts

@@ -0,0 +1,45 @@
+import {
+  requireNativeModule,
+  requireOptionalNativeModule,
+} from 'expo-modules-core';
+import type { ProcessedColorValue } from 'react-native';
+
+import type { UnloadFontOptions } from './types';
+
+export type INativeFontLoaderModule = {
+  getLoadedFonts(): string[];
+  loadAsync(fontFamilyName: string, localUri: string): Promise<void>;
+  unloadAllAsync?(): Promise<void>;
+  unloadAsync?(
+    fontFamilyName: string,
+    options?: UnloadFontOptions,
+  ): Promise<void>;
+};
+
+export type INativeRenderToImageOptions = {
+  fontFamily?: string;
+  size?: number;
+  color?: ProcessedColorValue;
+  lineHeight?: number;
+};
+
+export type INativeFontUtilsModule = {
+  renderToImageAsync(
+    glyphs: string,
+    options?: INativeRenderToImageOptions,
+  ): Promise<{ uri: string; width: number; height: number; scale: number }>;
+};
+
+const EXPO_FONT_LOADER_MODULE_NAME = 'ExpoFontLoader';
+const EXPO_FONT_UTILS_MODULE_NAME = 'ExpoFontUtils';
+
+export const expoFontLoader = requireNativeModule<INativeFontLoaderModule>(
+  EXPO_FONT_LOADER_MODULE_NAME,
+);
+
+// Present on both iOS and Android upstream — still optional (matches upstream's own
+// requireOptionalNativeModule) since only web ships without it.
+export const expoFontUtils =
+  requireOptionalNativeModule<INativeFontUtilsModule>(
+    EXPO_FONT_UTILS_MODULE_NAME,
+  );

package/src/core/types.ts

@@ -0,0 +1,25 @@
+// Ported from expo-font/src/Font.types.ts (sdk-57) — full parity, including the `number`
+// (require() module) and `Asset` instance source forms, both resolved via @symbiote-native/asset.
+import type { Asset } from '@symbiote-native/asset';
+
+/** @platform web — has no effect on native, kept for API-surface parity with upstream. */
+export enum FontDisplay {
+  AUTO = 'auto',
+  SWAP = 'swap',
+  BLOCK = 'block',
+  FALLBACK = 'fallback',
+  OPTIONAL = 'optional',
+}
+
+export type FontResource = {
+  uri?: string | number;
+  display?: FontDisplay;
+  default?: string;
+  testString?: string;
+};
+
+export type FontSource = string | number | Asset | FontResource;
+
+export type UnloadFontOptions = Pick<FontResource, 'display'>;
+
+export type UseFontsResult = readonly [loaded: boolean, error: Error | null];

package/src/react/hooks/use-fonts/index.ts

@@ -0,0 +1,36 @@
+// React lifecycle wiring over the framework-agnostic core (core/font.ts). Loads once on mount
+// (upstream's own contract: a changed font map is not reloaded — see FontHooks.ts's
+// useRuntimeFonts), seeded synchronously so an already-loaded font never flashes unloaded.
+import { useEffect, useState } from 'react';
+import {
+  isFontMapLoaded,
+  loadAsync,
+  type FontSource,
+  type UseFontsResult,
+} from '../../../core';
+
+export function useFonts(
+  map: string | Record<string, FontSource>,
+): UseFontsResult {
+  const [loaded, setLoaded] = useState(() => isFontMapLoaded(map));
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    let isMounted = true;
+    loadAsync(map)
+      .then(() => {
+        if (isMounted) setLoaded(true);
+      })
+      .catch((err: Error) => {
+        if (isMounted) setError(err);
+      });
+    return () => {
+      isMounted = false;
+    };
+    // Loads once on mount only — a later change to `map` is deliberately not reloaded,
+    // matching upstream's own useFonts contract.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return [loaded, error];
+}

package/src/react/index.ts

@@ -0,0 +1,4 @@
+// @symbiote-native/font/react: the React entry over the framework-agnostic core.
+
+export { useFonts } from './hooks/use-fonts';
+export * from '../core';

package/src/solid/index.ts

@@ -0,0 +1,6 @@
+// @symbiote-native/font/solid: the Solid entry over the framework-agnostic core — mirrors the
+// lifecycle-bucket naming convention of adapters/solid/src/primitives (never `hooks`/
+// `composables`/`runes`, those are React's, Vue's and Svelte's terms).
+
+export { createFonts } from './primitives/create-fonts';
+export * from '../core';

package/src/solid/primitives/create-fonts.ts

@@ -0,0 +1,18 @@
+// createFonts — the Solid twin of React's useFonts hook, over the framework-agnostic core
+// (core/font.ts). Loads once from the primitive body, matching upstream's own contract.
+import { createSignal, type Accessor } from 'solid-js';
+import { isFontMapLoaded, loadAsync, type FontSource } from '../../core';
+
+export function createFonts(map: string | Record<string, FontSource>): {
+  loaded: Accessor<boolean>;
+  error: Accessor<Error | null>;
+} {
+  const [loaded, setLoaded] = createSignal(isFontMapLoaded(map));
+  const [error, setError] = createSignal<Error | null>(null);
+
+  loadAsync(map)
+    .then(() => setLoaded(true))
+    .catch(setError);
+
+  return { loaded, error };
+}

package/src/svelte/index.ts

@@ -0,0 +1,6 @@
+// @symbiote-native/font/svelte: the Svelte entry over the framework-agnostic core — mirrors the
+// lifecycle-bucket naming convention of adapters/svelte/src/runes (never `hooks`/`composables`,
+// those are React's and Vue's terms).
+
+export { useFonts } from './runes/use-fonts.svelte';
+export * from '../core';

package/src/svelte/runes/use-fonts.svelte.ts

@@ -0,0 +1,30 @@
+// Svelte lifecycle wiring over the framework-agnostic core (core/font.ts). Loads once per
+// mount, matching upstream's own useFonts contract (a changed font map is not reloaded).
+import { isFontMapLoaded, loadAsync, type FontSource } from '../../core';
+
+export function useFonts(map: string | Record<string, FontSource>): {
+  readonly loaded: boolean;
+  readonly error: Error | null;
+} {
+  let loaded = $state(isFontMapLoaded(map));
+  let error = $state<Error | null>(null);
+
+  $effect(() => {
+    loadAsync(map)
+      .then(() => {
+        loaded = true;
+      })
+      .catch((err: Error) => {
+        error = err;
+      });
+  });
+
+  return {
+    get loaded(): boolean {
+      return loaded;
+    },
+    get error(): Error | null {
+      return error;
+    },
+  };
+}

package/src/svelte/svelte-ambient.d.ts

@@ -0,0 +1,3 @@
+// Pulls in svelte's ambient global declarations ($state/$effect/...) for this package's tsc
+// program — see packages/network's identical file for the full rationale.
+/// <reference types="svelte" />

package/src/vue/composables/use-fonts/index.ts

@@ -0,0 +1,24 @@
+// Vue lifecycle wiring over the framework-agnostic core (core/font.ts). Loads once on mount,
+// matching upstream's own useFonts contract (a changed font map prop is not reloaded).
+import { onMounted, ref, type Ref } from '@vue/runtime-core';
+import { isFontMapLoaded, loadAsync, type FontSource } from '../../../core';
+
+export function useFonts(map: string | Record<string, FontSource>): {
+  loaded: Ref<boolean>;
+  error: Ref<Error | null>;
+} {
+  const loaded = ref(isFontMapLoaded(map));
+  const error = ref<Error | null>(null);
+
+  onMounted(() => {
+    loadAsync(map)
+      .then(() => {
+        loaded.value = true;
+      })
+      .catch((err: Error) => {
+        error.value = err;
+      });
+  });
+
+  return { loaded, error };
+}