flowboard-react 0.6.8 → 0.6.10

package/src/components/layout/stackOverlayModel.ts

@@ -0,0 +1,185 @@
+import type { ViewStyle } from 'react-native';
+import { parseDimension } from '../../utils/flowboardUtils';
+
+type StackFitBehavior = 'loose' | 'expand';
+type StackClipBehavior = 'none' | 'hardEdge';
+
+const POSITION_KEYS = ['top', 'right', 'bottom', 'left'] as const;
+
+type OverlayAlignment =
+  | 'topStart'
+  | 'top'
+  | 'topEnd'
+  | 'centerStart'
+  | 'start'
+  | 'center'
+  | 'centerEnd'
+  | 'end'
+  | 'bottomStart'
+  | 'bottom'
+  | 'bottomEnd';
+
+const AMBIGUOUS_OVERLAY_ALIGNMENTS: ReadonlySet<OverlayAlignment> = new Set([
+  'start',
+  'center',
+  'end',
+  'centerStart',
+  'centerEnd',
+]);
+
+function hasPositioning(props: Record<string, any> | undefined): boolean {
+  if (!props || typeof props !== 'object') return false;
+  return POSITION_KEYS.some(
+    (key) => props[key] !== undefined && props[key] !== null
+  );
+}
+
+export function isPositionedChild(
+  child: Record<string, any> | undefined
+): boolean {
+  if (!child || typeof child !== 'object') return false;
+  if (String(child.type ?? '') === 'positioned') return true;
+  return hasPositioning((child.properties ?? {}) as Record<string, any>);
+}
+
+export function isOverlayStack(
+  children: Array<Record<string, any>> | undefined,
+  props: Record<string, any>
+): boolean {
+  if (String(props.axis ?? '').toLowerCase() === 'overlay') return true;
+  if (String(props.mode ?? '').toLowerCase() === 'overlay') return true;
+  return (children ?? []).some((child) => isPositionedChild(child));
+}
+
+function parseOverlayAlignment(value: unknown): OverlayAlignment | undefined {
+  const raw = String(value ?? '').trim();
+  switch (raw) {
+    case 'topStart':
+    case 'top':
+    case 'topEnd':
+    case 'centerStart':
+    case 'start':
+    case 'center':
+    case 'centerEnd':
+    case 'end':
+    case 'bottomStart':
+    case 'bottom':
+    case 'bottomEnd':
+      return raw;
+    case 'topLeft':
+      return 'topStart';
+    case 'topCenter':
+      return 'top';
+    case 'topRight':
+      return 'topEnd';
+    case 'centerLeft':
+      return 'start';
+    case 'centerRight':
+      return 'end';
+    case 'bottomLeft':
+      return 'bottomStart';
+    case 'bottomCenter':
+      return 'bottom';
+    case 'bottomRight':
+      return 'bottomEnd';
+    default:
+      return undefined;
+  }
+}
+
+function normalizeOverlayAlignment(value: unknown): OverlayAlignment {
+  return parseOverlayAlignment(value) ?? 'topStart';
+}
+
+export function resolveAlignmentToCss(
+  value: unknown
+): Pick<ViewStyle, 'justifyContent' | 'alignItems'> {
+  switch (normalizeOverlayAlignment(value)) {
+    case 'topStart':
+      return { justifyContent: 'flex-start', alignItems: 'flex-start' };
+    case 'top':
+      return { justifyContent: 'flex-start', alignItems: 'center' };
+    case 'topEnd':
+      return { justifyContent: 'flex-start', alignItems: 'flex-end' };
+    case 'centerStart':
+    case 'start':
+      return { justifyContent: 'center', alignItems: 'flex-start' };
+    case 'centerEnd':
+    case 'end':
+      return { justifyContent: 'center', alignItems: 'flex-end' };
+    case 'bottomStart':
+      return { justifyContent: 'flex-end', alignItems: 'flex-start' };
+    case 'bottom':
+      return { justifyContent: 'flex-end', alignItems: 'center' };
+    case 'bottomEnd':
+      return { justifyContent: 'flex-end', alignItems: 'flex-end' };
+    case 'center':
+    default:
+      return { justifyContent: 'center', alignItems: 'center' };
+  }
+}
+
+export function resolveOverlayAlignmentValue(
+  props: Record<string, any> | undefined
+): OverlayAlignment {
+  const overlayAlignment = parseOverlayAlignment(props?.overlayAlignment);
+  const alignment = parseOverlayAlignment(props?.alignment);
+
+  if (overlayAlignment) {
+    if (!alignment) return overlayAlignment;
+    if (
+      AMBIGUOUS_OVERLAY_ALIGNMENTS.has(alignment) &&
+      !AMBIGUOUS_OVERLAY_ALIGNMENTS.has(overlayAlignment)
+    ) {
+      return overlayAlignment;
+    }
+    return alignment;
+  }
+
+  return alignment ?? 'topStart';
+}
+
+export function resolveFitBehavior(value: unknown): StackFitBehavior {
+  return String(value ?? '').toLowerCase() === 'expand' ? 'expand' : 'loose';
+}
+
+export function resolveClipBehavior(value: unknown): StackClipBehavior {
+  return String(value ?? '').toLowerCase() === 'hardedge' ? 'hardEdge' : 'none';
+}
+
+function parsePositionDimension(value: any): number | string | undefined {
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    const lowered = trimmed.toLowerCase();
+    if (
+      lowered === 'double.infinity' ||
+      lowered === 'infinite' ||
+      lowered === 'infinity' ||
+      lowered === '+infinity'
+    ) {
+      return Number.POSITIVE_INFINITY;
+    }
+    if (trimmed.endsWith('%')) {
+      const numeric = Number(trimmed.slice(0, -1));
+      if (!Number.isNaN(numeric) && Number.isFinite(numeric)) {
+        return `${numeric}%`;
+      }
+    }
+  }
+  return parseDimension(value);
+}
+
+export function resolvePositionedStyle(
+  positionProps: Record<string, any> | undefined
+): ViewStyle {
+  const props = positionProps ?? {};
+  return {
+    position: 'absolute',
+    left: parsePositionDimension(props.left),
+    top: parsePositionDimension(props.top),
+    right: parsePositionDimension(props.right),
+    bottom: parsePositionDimension(props.bottom),
+    width: parsePositionDimension(props.width),
+    height: parsePositionDimension(props.height),
+  };
+}

package/src/fonts/fontLoader.ts

@@ -0,0 +1,426 @@
+import type { ResolvedFontSpec } from './fontResolver';
+
+type ExpoFontLoadAsync = (
+  fontMap: Record<string, unknown>
+) => Promise<void> | void;
+
+type DynamicNativeFontLoader = (
+  name: string,
+  data: string,
+  type?: 'ttf' | 'otf'
+) => Promise<string | void> | string | void;
+
+const WEIGHT_SUFFIX_BY_VALUE: Record<number, string> = {
+  100: 'Thin',
+  200: 'ExtraLight',
+  300: 'Light',
+  400: 'Regular',
+  500: 'Medium',
+  600: 'SemiBold',
+  700: 'Bold',
+  800: 'ExtraBold',
+  900: 'Black',
+};
+
+export type FontProviderRequest = {
+  spec: ResolvedFontSpec;
+  nativeFontName: string;
+};
+
+export type FontProvider = {
+  loadFont: (
+    request: FontProviderRequest
+  ) => Promise<boolean | string | void> | boolean | string | void;
+};
+
+const loadedFontKeys = new Set<string>();
+const inFlightLoads = new Map<string, Promise<void>>();
+const loadedFontFamilyByKey = new Map<string, string>();
+const subscribers = new Set<() => void>();
+const warnedMissingProviders = new Set<string>();
+
+const expoGoogleFontModuleByFamily = new Map<
+  string,
+  Record<string, unknown> | null
+>();
+
+let customFontProvider: FontProvider | null = null;
+
+let dynamicRequire: ((moduleName: string) => any) | null = null;
+try {
+  // eslint-disable-next-line no-eval
+  const runtimeRequire = eval('require') as unknown;
+  if (typeof runtimeRequire === 'function') {
+    dynamicRequire = runtimeRequire as (moduleName: string) => any;
+  }
+} catch {
+  dynamicRequire = null;
+}
+
+function safeDynamicRequire(moduleName: string): any | null {
+  if (!dynamicRequire) return null;
+  try {
+    return dynamicRequire(moduleName);
+  } catch {
+    return null;
+  }
+}
+
+function isDevMode(): boolean {
+  return (
+    (globalThis as { __DEV__?: boolean }).__DEV__ ??
+    process.env.NODE_ENV !== 'production'
+  );
+}
+
+function isDebugEnabled(): boolean {
+  const runtimeFlag =
+    (globalThis as { __FLOWBOARD_FONT_DEBUG__?: boolean })
+      .__FLOWBOARD_FONT_DEBUG__ === true;
+  const envFlag = String(process.env.FLOWBOARD_FONT_DEBUG ?? '') === '1';
+  return isDevMode() && (runtimeFlag || envFlag);
+}
+
+function debugLog(event: string, payload: Record<string, unknown>): void {
+  if (!isDebugEnabled()) return;
+  console.log(`[flowboard-react][fonts] ${event}`, JSON.stringify(payload));
+}
+
+function notifySubscribers(): void {
+  subscribers.forEach((subscriber) => {
+    try {
+      subscriber();
+    } catch {
+      // Ignore subscriber callback errors.
+    }
+  });
+}
+
+function normalizeGooglePackageSlug(family: string): string {
+  return family
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function resolveExpoGoogleFontModule(
+  family: string
+): Record<string, unknown> | null {
+  if (expoGoogleFontModuleByFamily.has(family)) {
+    return expoGoogleFontModuleByFamily.get(family) ?? null;
+  }
+
+  const packageSlug = normalizeGooglePackageSlug(family);
+  if (!packageSlug) {
+    expoGoogleFontModuleByFamily.set(family, null);
+    return null;
+  }
+
+  const maybeModule = safeDynamicRequire(`@expo-google-fonts/${packageSlug}`);
+  const normalizedModule =
+    maybeModule && typeof maybeModule === 'object'
+      ? (maybeModule as Record<string, unknown>)
+      : null;
+  expoGoogleFontModuleByFamily.set(family, normalizedModule);
+  return normalizedModule;
+}
+
+function listExpoGoogleNativeNames(family: string): string[] {
+  const module = resolveExpoGoogleFontModule(family);
+  if (!module) return [];
+  return Object.keys(module).filter((key) => /_(\d{3})[A-Za-z]+$/.test(key));
+}
+
+function resolveExpoNativeName(
+  family: string,
+  weight: number | undefined
+): string | undefined {
+  const nativeNames = listExpoGoogleNativeNames(family);
+  if (nativeNames.length === 0) return undefined;
+
+  if (weight === undefined) {
+    const regular = nativeNames.find((name) => /_400[A-Za-z]+$/.test(name));
+    if (regular) return regular;
+    return nativeNames[0];
+  }
+
+  const candidates = nativeNames.filter((name) =>
+    new RegExp(`_${weight}[A-Za-z]+$`).test(name)
+  );
+  if (candidates.length === 0) return undefined;
+
+  const preferredSuffix = WEIGHT_SUFFIX_BY_VALUE[weight];
+  if (preferredSuffix) {
+    const preferred = candidates.find((name) => name.endsWith(preferredSuffix));
+    if (preferred) return preferred;
+  }
+
+  const nonItalic = candidates.find((name) => !/italic$/i.test(name));
+  return nonItalic ?? candidates[0];
+}
+
+function toNativeFamilyPrefix(family: string): string {
+  const segments = family.match(/[a-z0-9]+/gi) ?? [];
+  if (segments.length === 0) return 'Font';
+  return segments
+    .map((segment) => {
+      const lower = segment.toLowerCase();
+      return `${lower.charAt(0).toUpperCase()}${lower.slice(1)}`;
+    })
+    .join('');
+}
+
+function buildFallbackNativeName(
+  family: string,
+  weight: number | undefined
+): string {
+  if (weight === undefined) return toNativeFamilyPrefix(family);
+  const suffix = WEIGHT_SUFFIX_BY_VALUE[weight] ?? 'Regular';
+  return `${toNativeFamilyPrefix(family)}_${weight}${suffix}`;
+}
+
+function resolveNativeFontName(spec: ResolvedFontSpec): string {
+  const expoNative = resolveExpoNativeName(
+    spec.resolvedFamily,
+    spec.resolvedWeight
+  );
+  if (expoNative) return expoNative;
+  return buildFallbackNativeName(spec.resolvedFamily, spec.resolvedWeight);
+}
+
+export function resolveNativeFontFamilyName(spec: ResolvedFontSpec): string {
+  return resolveNativeFontName(spec);
+}
+
+function resolveExpoLoadAsync(): ExpoFontLoadAsync | null {
+  const expoFontModule = safeDynamicRequire('expo-font');
+  if (!expoFontModule) return null;
+  const loadAsync =
+    expoFontModule.loadAsync ??
+    expoFontModule.default?.loadAsync ??
+    expoFontModule.Font?.loadAsync;
+  return typeof loadAsync === 'function'
+    ? (loadAsync as ExpoFontLoadAsync)
+    : null;
+}
+
+function resolveDynamicNativeFontLoader(): DynamicNativeFontLoader | null {
+  const dynamicFontsModule = safeDynamicRequire('react-native-dynamic-fonts');
+  if (!dynamicFontsModule) return null;
+  const loadFont =
+    dynamicFontsModule.loadFont ?? dynamicFontsModule.default?.loadFont;
+  return typeof loadFont === 'function'
+    ? (loadFont as DynamicNativeFontLoader)
+    : null;
+}
+
+function resolveFontAssetUri(fontAsset: unknown): string | undefined {
+  if (typeof fontAsset === 'string' && fontAsset.trim()) {
+    return fontAsset.trim();
+  }
+
+  const reactNativeModule = safeDynamicRequire('react-native');
+  const resolveAssetSource =
+    reactNativeModule?.Image?.resolveAssetSource ??
+    reactNativeModule?.default?.Image?.resolveAssetSource;
+
+  if (
+    typeof resolveAssetSource === 'function' &&
+    (typeof fontAsset === 'number' ||
+      (fontAsset && typeof fontAsset === 'object'))
+  ) {
+    try {
+      const resolvedSource = resolveAssetSource(fontAsset);
+      if (
+        resolvedSource &&
+        typeof resolvedSource.uri === 'string' &&
+        resolvedSource.uri.trim()
+      ) {
+        return resolvedSource.uri.trim();
+      }
+    } catch {
+      return undefined;
+    }
+  }
+
+  return undefined;
+}
+
+function inferFontTypeFromUri(uri: string): 'ttf' | 'otf' {
+  return /\.otf(?:\?|$)/i.test(uri) ? 'otf' : 'ttf';
+}
+
+function arrayBufferToBase64(buffer: ArrayBuffer): string | null {
+  const bufferModule = safeDynamicRequire('buffer');
+  const BufferCtor = bufferModule?.Buffer;
+  if (typeof BufferCtor !== 'function') return null;
+  return BufferCtor.from(buffer).toString('base64');
+}
+
+async function tryLoadWithDynamicFonts(
+  nativeFontName: string,
+  fontAsset: unknown
+): Promise<string | false> {
+  const loadFont = resolveDynamicNativeFontLoader();
+  if (!loadFont) return false;
+
+  const uri = resolveFontAssetUri(fontAsset);
+  if (!uri) return false;
+
+  try {
+    const response = await fetch(uri);
+    if (!response.ok) return false;
+    const buffer = await response.arrayBuffer();
+    const base64 = arrayBufferToBase64(buffer);
+    if (!base64) return false;
+
+    const loadedName = await Promise.resolve(
+      loadFont(nativeFontName, base64, inferFontTypeFromUri(uri))
+    );
+    if (typeof loadedName === 'string' && loadedName.trim()) {
+      return loadedName.trim();
+    }
+    return nativeFontName;
+  } catch {
+    return false;
+  }
+}
+
+async function tryLoadWithExpo(
+  spec: ResolvedFontSpec
+): Promise<string | false> {
+  const nativeFontName = resolveNativeFontName(spec);
+  const packageModule = resolveExpoGoogleFontModule(spec.resolvedFamily);
+  if (!packageModule) return false;
+
+  const fontAsset = packageModule[nativeFontName];
+  if (!fontAsset) return false;
+
+  const loadAsync = resolveExpoLoadAsync();
+  if (!loadAsync) {
+    return tryLoadWithDynamicFonts(nativeFontName, fontAsset);
+  }
+
+  await Promise.resolve(loadAsync({ [nativeFontName]: fontAsset }));
+  return nativeFontName;
+}
+
+function warnMissingProvider(
+  spec: ResolvedFontSpec,
+  nativeFontName: string
+): void {
+  if (!isDevMode()) return;
+  const key = `${spec.fontKey}:${nativeFontName}`;
+  if (warnedMissingProviders.has(key)) return;
+  warnedMissingProviders.add(key);
+  console.warn(
+    `[flowboard-react] Unable to load Google Font "${spec.resolvedFamily}" (${nativeFontName}). ` +
+      'Install `expo-font` + `@expo-google-fonts/<family>` (Expo), or `react-native-dynamic-fonts` + `@expo-google-fonts/<family>` (bare React Native), or register a Google font provider with `setFontProvider`.'
+  );
+}
+
+export function setFontProvider(provider: FontProvider | null): void {
+  customFontProvider = provider;
+}
+
+export function isFontLoaded(spec: ResolvedFontSpec): boolean {
+  return loadedFontKeys.has(spec.fontKey);
+}
+
+export function getLoadedFontFamily(
+  spec: ResolvedFontSpec
+): string | undefined {
+  return loadedFontFamilyByKey.get(spec.fontKey);
+}
+
+export function resolveAppliedFontFamily(
+  spec: ResolvedFontSpec
+): string | undefined {
+  return getLoadedFontFamily(spec) ?? spec.resolvedFamily;
+}
+
+export async function ensureFontLoaded(spec: ResolvedFontSpec): Promise<void> {
+  if (!spec.resolvedFamily) return;
+  if (loadedFontKeys.has(spec.fontKey)) return;
+
+  const pending = inFlightLoads.get(spec.fontKey);
+  if (pending) return pending;
+
+  const nativeFontName = resolveNativeFontName(spec);
+  const loadPromise = (async () => {
+    const customLoaded = customFontProvider
+      ? await Promise.resolve(
+          customFontProvider.loadFont({
+            spec,
+            nativeFontName,
+          })
+        )
+      : false;
+
+    if (typeof customLoaded === 'string' && customLoaded.trim()) {
+      loadedFontKeys.add(spec.fontKey);
+      loadedFontFamilyByKey.set(spec.fontKey, customLoaded.trim());
+      debugLog('loaded', {
+        family: spec.resolvedFamily,
+        weight: spec.resolvedWeight,
+        provider: 'custom',
+      });
+      notifySubscribers();
+      return;
+    }
+
+    if (customLoaded === true) {
+      loadedFontKeys.add(spec.fontKey);
+      loadedFontFamilyByKey.set(spec.fontKey, nativeFontName);
+      debugLog('loaded', {
+        family: spec.resolvedFamily,
+        weight: spec.resolvedWeight,
+        provider: 'custom',
+      });
+      notifySubscribers();
+      return;
+    }
+
+    const expoLoaded = await tryLoadWithExpo(spec);
+    if (expoLoaded) {
+      loadedFontKeys.add(spec.fontKey);
+      loadedFontFamilyByKey.set(spec.fontKey, expoLoaded);
+      debugLog('loaded', {
+        family: spec.resolvedFamily,
+        weight: spec.resolvedWeight,
+        provider: 'expo',
+      });
+      notifySubscribers();
+      return;
+    }
+
+    debugLog('fallback', {
+      family: spec.resolvedFamily,
+      requestedWeight: spec.resolvedWeight,
+    });
+    warnMissingProvider(spec, nativeFontName);
+  })().finally(() => {
+    inFlightLoads.delete(spec.fontKey);
+  });
+
+  inFlightLoads.set(spec.fontKey, loadPromise);
+  return loadPromise;
+}
+
+export function subscribeFontLoad(listener: () => void): () => void {
+  subscribers.add(listener);
+  return () => {
+    subscribers.delete(listener);
+  };
+}
+
+export function __resetFontLoaderForTests(): void {
+  loadedFontKeys.clear();
+  inFlightLoads.clear();
+  loadedFontFamilyByKey.clear();
+  subscribers.clear();
+  warnedMissingProviders.clear();
+  expoGoogleFontModuleByFamily.clear();
+  customFontProvider = null;
+}

package/src/fonts/fontResolver.ts

@@ -0,0 +1,69 @@
+import { normalizeFamilyName, pickWeight } from './googleFontCatalog';
+
+export type ResolveFontSpecInput = {
+  family: string;
+  requestedWeight?: number;
+};
+
+export type ResolvedFontSpec = {
+  resolvedFamily: string;
+  resolvedWeight?: number;
+  fontKey: string;
+};
+
+function normalizeFontKeyFamily(family: string): string {
+  return family
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function isFontDebugEnabled(): boolean {
+  const runtimeFlag =
+    (globalThis as { __FLOWBOARD_FONT_DEBUG__?: boolean })
+      .__FLOWBOARD_FONT_DEBUG__ === true;
+  const envFlag =
+    typeof process !== 'undefined' &&
+    String(process.env.FLOWBOARD_FONT_DEBUG ?? '').toLowerCase() === '1';
+  const devMode =
+    (globalThis as { __DEV__?: boolean }).__DEV__ ??
+    process.env.NODE_ENV !== 'production';
+  return devMode && (runtimeFlag || envFlag);
+}
+
+function logResolution(
+  family: string,
+  requestedWeight: number | undefined,
+  resolvedWeight: number | undefined
+): void {
+  if (!isFontDebugEnabled()) return;
+  const fallback =
+    requestedWeight !== undefined && resolvedWeight !== requestedWeight;
+  console.log(
+    '[flowboard-react][fonts] resolve',
+    JSON.stringify({
+      family,
+      requestedWeight,
+      resolvedWeight,
+      fallback,
+    })
+  );
+}
+
+export function resolveFontSpec({
+  family,
+  requestedWeight,
+}: ResolveFontSpecInput): ResolvedFontSpec {
+  const resolvedFamily = normalizeFamilyName(family);
+  const resolvedWeight = pickWeight(resolvedFamily, requestedWeight);
+  const fontKeyFamily = normalizeFontKeyFamily(resolvedFamily) || 'font';
+  const fontKey = `${fontKeyFamily}-${resolvedWeight ?? 'base'}`;
+
+  logResolution(resolvedFamily, requestedWeight, resolvedWeight);
+
+  return {
+    resolvedFamily,
+    resolvedWeight,
+    fontKey,
+  };
+}