@newtonedev/components 0.1.7 → 0.1.8

package/src/fonts/useLocalCalibration.ts

@@ -0,0 +1,97 @@
+import { useState, useEffect } from 'react';
+import { measureAvgCharWidth } from './measureFont';
+
+const STORAGE_KEY = 'newtone:font-metrics:v1';
+const TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+interface CacheEntry {
+  readonly ratio: number;
+  readonly measuredAt: number;
+}
+
+type FontMetricsCache = Record<string, CacheEntry>;
+
+function readCache(): FontMetricsCache {
+  if (typeof localStorage === 'undefined') return {};
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    return raw ? (JSON.parse(raw) as FontMetricsCache) : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeCache(cache: FontMetricsCache): void {
+  if (typeof localStorage === 'undefined') return;
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(cache));
+  } catch {
+    // Ignore write errors (quota exceeded, private browsing)
+  }
+}
+
+function cacheKey(fontFamily: string, fontWeight: number): string {
+  return `${fontFamily}:${fontWeight}`;
+}
+
+/**
+ * Returns the avgCharWidth ratio for a font, using a device-local measurement
+ * cached in localStorage (Layer 2 calibration).
+ *
+ * Resolution order:
+ * 1. localStorage cache (if fresh, < 7 days old)
+ * 2. `baseCalibration` (Layer 1 — editor-time canvas measurement from theme config)
+ * 3. 0.55 (fallback constant)
+ *
+ * On mount, measures the font if the cache is stale or absent, then updates
+ * localStorage and triggers a re-render with the device-accurate ratio.
+ *
+ * @param fontFamily    - CSS font family name, e.g. "Inter"
+ * @param fontWeight    - CSS font-weight number, e.g. 400
+ * @param fallback      - CSS fallback stack, e.g. "sans-serif"
+ * @param baseCalibration - Layer 1 ratio from `themeConfig.typography.calibrations`
+ */
+export function useLocalCalibration(
+  fontFamily: string,
+  fontWeight: number,
+  fallback: string,
+  baseCalibration?: number,
+): number {
+  const key = cacheKey(fontFamily, fontWeight);
+
+  // Initialise synchronously from cache so the first render uses a calibrated ratio
+  const [ratio, setRatio] = useState<number>(() => {
+    const cache = readCache();
+    const entry = cache[key];
+    if (entry && Date.now() - entry.measuredAt < TTL_MS) {
+      return entry.ratio;
+    }
+    return baseCalibration ?? 0.55;
+  });
+
+  useEffect(() => {
+    const cache = readCache();
+    const entry = cache[key];
+    if (entry && Date.now() - entry.measuredAt < TTL_MS) {
+      // Cache is fresh — no re-measurement needed
+      if (entry.ratio !== ratio) setRatio(entry.ratio);
+      return;
+    }
+
+    // Cache is stale or absent — measure in the background
+    let cancelled = false;
+    measureAvgCharWidth(fontFamily, fontWeight, fallback).then((measured) => {
+      if (cancelled) return;
+      const updated = { ...readCache(), [key]: { ratio: measured, measuredAt: Date.now() } };
+      writeCache(updated);
+      setRatio(measured);
+    });
+    return () => {
+      cancelled = true;
+    };
+    // Intentionally excluding `ratio` from deps — we only want to re-measure on key/font change
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, fontFamily, fontWeight, fallback]);
+
+  return ratio;
+}

package/src/fonts/useTypographyCalibrations.ts

@@ -0,0 +1,15 @@
+import { useNewtoneTheme } from '../theme/NewtoneProvider';
+
+/**
+ * Returns the per-font avgCharWidth calibrations from the current theme config.
+ *
+ * These are Layer 1 (editor-time) calibrations — measured with canvas at publish
+ * time and stored in `themeConfig.typography.calibrations`. Use `useLocalCalibration`
+ * to overlay device-local (Layer 2) measurements on top.
+ *
+ * @returns Record of fontFamily → avgCharWidthRatio, or an empty object if absent.
+ */
+export function useTypographyCalibrations(): Record<string, number> {
+  const { config } = useNewtoneTheme();
+  return config.typography.calibrations ?? {};
+}

package/src/index.ts

@@ -8,11 +8,18 @@ export type {
   NewtoneThemeConfig,
   NewtoneThemeContext,
   FontConfig,
+  FontWeights,
+  FontSlot,
   TokenOverrides,
+  FontSizeScale,
+  LineHeightScale,
+  RoleSizeStep,
+  RoleScale,
+  RoleScales,
 } from './theme/types';
 export { useFrameContext } from './theme/FrameContext';
 export type { FrameContextValue } from './theme/FrameContext';
-export { DEFAULT_THEME_CONFIG } from './theme/defaults';
+export { DEFAULT_THEME_CONFIG, DEFAULT_FONT_SIZES, DEFAULT_LINE_HEIGHTS, DEFAULT_ROLE_SCALES } from './theme/defaults';
 
 // Tokens
 export { useTokens } from './tokens/useTokens';
@@ -88,16 +95,17 @@ export type { IconProps } from './primitives/Icon/Icon.types';
 export { Wrapper } from './primitives/Wrapper/Wrapper';
 export type { WrapperProps } from './primitives/Wrapper/Wrapper.types';
 
-export { Text } from './primitives/Text/Text';
+export { Text } from './primitives/Text';
 export type {
   TextProps,
   TextSize,
   TextWeight,
   TextColor,
-  TextFont,
-  TextLineHeight,
+  TextScope,
+  TextRole,
   TextAlign,
-} from './primitives/Text/Text.types';
+  TextSpanProps,
+} from './primitives/Text';
 
 export { AppShell } from './composites/layout/AppShell/AppShell';
 export type { AppShellProps } from './composites/layout/AppShell/AppShell.types';
@@ -128,9 +136,10 @@ export {
 } from './registry';
 
 // Fonts
-export { GOOGLE_FONTS, SYSTEM_FONTS } from './fonts/googleFonts';
-export type { GoogleFontEntry, SystemFontEntry } from './fonts/googleFonts';
 export { buildGoogleFontsUrl } from './fonts/buildGoogleFontsUrl';
+export { measureAvgCharWidth } from './fonts/measureFont';
+export { useLocalCalibration } from './fonts/useLocalCalibration';
+export { useTypographyCalibrations } from './fonts/useTypographyCalibrations';
 
 // Re-export core engine types for convenience
 export type {

package/src/primitives/Frame/Frame.tsx

@@ -246,9 +246,9 @@ export function Frame({
   const textStyle = useMemo<TextStyle>(
     () => ({
       color: srgbToHex(tokens.textPrimary.srgb),
-      fontSize: tokens.typography.size.base,
-      fontFamily: tokens.typography.fonts.default,
-      lineHeight: tokens.typography.size.base * tokens.typography.lineHeight.normal,
+      fontSize: tokens.typography.fontSizes['05'],
+      fontFamily: tokens.typography.fonts.main.family,
+      lineHeight: tokens.typography.lineHeights['06'],
     }),
     [tokens],
   );

package/src/primitives/Icon/Icon.tsx

@@ -39,7 +39,7 @@ export function Icon({
   // instead of rebuilding the style object on every render.
   const iconStyle = useMemo<TextStyle>(() => {
     // Use the provided size, or fall back to the theme's default text size.
-    const fontSize = size ?? tokens.typography.size.base;
+    const fontSize = size ?? tokens.typography.fontSizes['05'];
 
     // Round to nearest Material Symbols optical size (20, 24, 40, 48)
     // for optimal stroke weight and detail rendering.

package/src/primitives/Icon/Icon.types.ts

@@ -25,7 +25,7 @@ export interface IconProps {
    */
   readonly name: string;
 
-  /** Font size in pixels. @default tokens.typography.size.base (~16px) */
+  /** Font size in pixels. @default tokens.typography.fontSizes['05'] (16px) */
   readonly size?: number;
 
   /** Optical size for variable font axis. Adjusts stroke weight for readability at small sizes. @default same as size */

package/src/primitives/Text/Text.spans.ts

@@ -0,0 +1,57 @@
+import React, { useContext, useMemo } from 'react';
+import { Text as RNText } from 'react-native';
+import type { TextStyle } from 'react-native';
+import { useTokens } from '../../tokens/useTokens';
+import { TextScopeContext, resolveTextColor } from './Text';
+import type { TextSpanProps, TextWeight } from './Text.types';
+
+/**
+ * Generic inline span — constrained sub-component for inline text formatting.
+ * Inherits font family, size, and line height from the parent Text.
+ * Only inline formatting properties (color, weight, italic, underline, highlight) are exposed.
+ */
+export function TextSpan({ children, color, weight, italic, underline, highlight, style }: TextSpanProps) {
+  const tokens = useTokens(1);
+  const scopeCtx = useContext(TextScopeContext);
+
+  const spanStyle = useMemo<TextStyle>(() => {
+    const s: TextStyle = {};
+    if (color) s.color = resolveTextColor(color, tokens);
+    if (weight && scopeCtx) s.fontWeight = String(scopeCtx.weights[weight]) as TextStyle['fontWeight'];
+    if (italic) s.fontStyle = 'italic';
+    if (underline) s.textDecorationLine = 'underline';
+    if (highlight) s.backgroundColor = resolveTextColor(highlight, tokens);
+    return s;
+  }, [tokens, scopeCtx, color, weight, italic, underline, highlight]);
+
+  return React.createElement(
+    RNText,
+    { style: style ? [spanStyle, ...(Array.isArray(style) ? style : [style])] : spanStyle },
+    children,
+  );
+}
+
+/** Bold span — applies bold weight inline. */
+export function TextBold(props: Omit<TextSpanProps, 'weight'>) {
+  return React.createElement(TextSpan, { ...props, weight: 'bold' as TextWeight });
+}
+
+/** Medium-weight span — applies medium weight inline. */
+export function TextMedium(props: Omit<TextSpanProps, 'weight'>) {
+  return React.createElement(TextSpan, { ...props, weight: 'medium' as TextWeight });
+}
+
+/** Italic span — applies italic style inline. */
+export function TextItalic(props: Omit<TextSpanProps, 'italic'>) {
+  return React.createElement(TextSpan, { ...props, italic: true });
+}
+
+/** Underline span — applies underline decoration inline. */
+export function TextUnderline(props: Omit<TextSpanProps, 'underline'>) {
+  return React.createElement(TextSpan, { ...props, underline: true });
+}
+
+/** Highlight span — applies background highlight using a semantic color token. */
+export function TextHighlight(props: Omit<TextSpanProps, 'highlight'> & { readonly highlight: TextSpanProps['highlight'] }) {
+  return React.createElement(TextSpan, props as TextSpanProps);
+}

package/src/primitives/Text/Text.tsx

@@ -1,16 +1,32 @@
-import React, { useMemo } from 'react';
-import { Text as RNText } from 'react-native';
-import type { TextStyle } from 'react-native';
+import React, { createContext, useMemo, useState, useEffect } from 'react';
+import { Text as RNText, View } from 'react-native';
+import type { LayoutChangeEvent, TextStyle } from 'react-native';
 import { srgbToHex } from 'newtone';
+import { resolveResponsiveSize, estimateLineWidths, BREAKPOINT_ROLE_SCALE, scaleRoleStep, REFERENCE_LINE_HEIGHT_RATIO, buildFontFeatureSettings, SEMANTIC_WEIGHT_MAP, ROLE_DEFAULT_WEIGHTS } from '@newtonedev/fonts';
 import { useTokens } from '../../tokens/useTokens';
+import { useNewtoneTheme } from '../../theme/NewtoneProvider';
 import type { UseTokensResult } from '../../tokens/useTokens';
 import type { TextProps, TextColor } from './Text.types';
+import { useLocalCalibration } from '../../fonts/useLocalCalibration';
+import { useTypographyCalibrations } from '../../fonts/useTypographyCalibrations';
+import { enqueueObservation } from '../../fonts/reportQueue';
+import { useBreakpoint } from '../../theme/useBreakpoint';
+
+/**
+ * Context to pass the active scope's weight map to span sub-components.
+ * Spans inherit font family from the parent RN Text, but need the scope's
+ * weight mapping to resolve semantic weight tokens (regular/medium/bold)
+ * to numeric CSS values.
+ */
+export const TextScopeContext = createContext<{
+  readonly weights: { readonly regular: number; readonly medium: number; readonly bold: number };
+} | null>(null);
 
 /**
  * Resolve a semantic text color to a hex string from the current tokens.
  * Neutral text colors are top-level; palette colors use nested PaletteTokens.fill.
  */
-function resolveTextColor(color: TextColor, tokens: UseTokensResult): string {
+export function resolveTextColor(color: TextColor, tokens: UseTokensResult): string {
   switch (color) {
     case 'primary': return srgbToHex(tokens.textPrimary.srgb);
     case 'secondary': return srgbToHex(tokens.textSecondary.srgb);
@@ -23,78 +39,214 @@ function resolveTextColor(color: TextColor, tokens: UseTokensResult): string {
   }
 }
 
+/** Adaptive roles that support responsive font sizing. */
+const ADAPTIVE_ROLES = new Set(['headline', 'title', 'heading', 'subheading']);
+
+/** Maps heading-like roles to HTML heading levels for semantic rendering on web. */
+const ROLE_HEADING_LEVEL: Readonly<Record<string, number>> = {
+  headline: 1,
+  title: 2,
+  heading: 3,
+};
+
+/** Estimate total character count from potentially nested React children. */
+function extractCharacterCount(node: React.ReactNode): number {
+  if (typeof node === 'string') return node.length;
+  if (typeof node === 'number') return String(node).length;
+  if (!node) return 0;
+  if (Array.isArray(node)) {
+    return node.reduce((sum: number, child) => sum + extractCharacterCount(child), 0);
+  }
+  if (typeof node === 'object' && 'props' in node) {
+    return extractCharacterCount((node as React.ReactElement).props?.children);
+  }
+  return 0;
+}
+
 /**
- * Token-aware text primitive.
+ * Token-aware text primitive with semantic scope + role API.
  *
- * Reads typography tokens from the nearest NewtoneProvider and maps
- * semantic props (size, weight, color, font, lineHeight) to resolved values.
+ * - `scope` selects the font family (main, display, mono, currency)
+ * - `role` sets default weight; fontSize and lineHeight resolved from config's role mapping
+ * - `size` selects within the role's 3-step scale (sm, md, lg)
+ * - `responsive` enables container-width-aware font sizing for adaptive roles
  *
  * @example
  * ```tsx
- * <Text>Body text</Text>
- * <Text size="sm" weight="semibold" color="secondary">Label</Text>
- * <Text size="xl" font="display">Heading</Text>
+ * <Text>Body text (default)</Text>
+ * <Text role="headline" scope="display">Hero title</Text>
+ * <Text role="label">Form label</Text>
+ * <Text scope="mono" role="caption">const x = 42;</Text>
+ * <Text role="body">Regular <Text.Bold>bold</Text.Bold> text</Text>
+ * <Text role="headline" responsive>Responsive headline</Text>
  * ```
  */
-export function Text({
+function TextBase({
   children,
-  size = 'base',
-  weight = 'regular',
+  scope = 'main',
+  role = 'body',
   color = 'primary',
-  font = 'default',
-  lineHeight = 'normal',
+  size: sizeOverride,
   align,
   numberOfLines,
   elevation = 1,
   style,
-  // Accessibility
-  accessibilityRole,
-  // Testing & platform
+  accessibilityRole: accessibilityRoleOverride,
   testID,
   nativeID,
   ref,
+  responsive = false,
+  centerVertically = false,
+  features,
 }: TextProps) {
-  // Get the current theme's design tokens (colors, fonts, spacing).
-  // The elevation parameter affects which background shade the tokens reference.
   const tokens = useTokens(elevation);
+  const { config, reportingEndpoint } = useNewtoneTheme();
+
+  const size = sizeOverride ?? 'md';
+  const fontSlot = tokens.typography.fonts[scope];
+  // roleWeights from config (user-customized), falling back to canonical defaults
+  const resolvedFontWeight = config.typography.roleWeights?.[role] ?? ROLE_DEFAULT_WEIGHTS[role];
+
+  // --- Breakpoint-aware step ---
+  const breakpoint = useBreakpoint();
+  const baseStep = config.typography.roles[role][size];
+  const bpScale = BREAKPOINT_ROLE_SCALE[breakpoint][role];
+  const step = bpScale === 1.0 ? baseStep : scaleRoleStep(baseStep, bpScale);
+
+  // --- Responsive sizing (Layer 2 calibration) ---
+  // Hooks are called unconditionally; results are used only when `responsive && isAdaptive`.
+  const calibrations = useTypographyCalibrations();
+  const fontSlotFull = config.typography.fonts[scope]; // FontSlot with config.fallback
+  const localRatio = useLocalCalibration(
+    fontSlot.family,
+    SEMANTIC_WEIGHT_MAP.regular,
+    fontSlotFull.config.fallback,
+    calibrations[fontSlot.family],
+  );
+
+  const isAdaptive = ADAPTIVE_ROLES.has(role);
+  const [containerWidth, setContainerWidth] = useState<number | null>(null);
+  const characterCount = useMemo(() => extractCharacterCount(children), [children]);
+
+  const resolvedStep = useMemo(
+    () =>
+      resolveResponsiveSize(
+        {
+          role,
+          size,
+          responsive: responsive && isAdaptive,
+          fontFamily: fontSlot.family,
+          maxFontSize: step.fontSize,
+          minFontSize: Math.max(8, Math.round(step.fontSize * 0.7)),
+        },
+        config.typography.roles,
+        containerWidth != null ? { containerWidth, characterCount } : undefined,
+        { [fontSlot.family]: localRatio },
+      ),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [role, size, responsive, isAdaptive, fontSlot.family, step.fontSize, config.typography.roles, containerWidth, characterCount, localRatio],
+  );
+
+  // --- Layer 3: report observations for cross-site rolling averages ---
+  useEffect(() => {
+    if (!reportingEndpoint || !responsive || !isAdaptive || containerWidth == null) return;
+    const lineWidths = estimateLineWidths(characterCount, containerWidth, resolvedStep.fontSize, localRatio);
+    const lastLine = lineWidths[lineWidths.length - 1];
+    enqueueObservation(reportingEndpoint, {
+      fontFamily: fontSlot.family,
+      fontWeight: resolvedFontWeight,
+      role,
+      size,
+      fontSize: resolvedStep.fontSize,
+      containerWidth,
+      characterCount,
+      lineCount: lineWidths.length,
+      lastLineRatio: containerWidth > 0 ? lastLine / containerWidth : 1,
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [reportingEndpoint, resolvedStep.fontSize, containerWidth]);
 
-  // Build the text style from the theme tokens.
-  // Wrapped in useMemo so it only recalculates when the inputs actually change,
-  // instead of recalculating on every render (which would be wasteful).
   const resolvedStyle = useMemo<TextStyle>(() => {
-    // Look up the pixel size for the chosen size token (e.g. 'base' → 16px).
-    const fontSize = tokens.typography.size[size];
+    const activeStep = responsive && isAdaptive ? resolvedStep : step;
+
+    // Font metrics corrections (adjustLineHeight, verticalCenterOffset, features)
+    const currentMetrics = config.typography.fontMetrics?.[fontSlot.family];
+
+    // Phase 3: Correct line height for font's natural vertical extent (snap to 4px grid)
+    const correctedLineHeight = currentMetrics
+      ? Math.round((activeStep.lineHeight * currentMetrics.naturalLineHeightRatio / REFERENCE_LINE_HEIGHT_RATIO) / 4) * 4
+      : activeStep.lineHeight;
+
+    // Phase 4: Visual centering correction (opt-in via centerVertically prop, snap to 0.5px)
+    const vcOffset = centerVertically && currentMetrics
+      ? Math.round(currentMetrics.verticalCenterOffset * activeStep.fontSize * 2) / 2
+      : 0;
+
+    // Phase 5: OpenType feature settings
+    const activeFeatures = features
+      ? (currentMetrics?.features ? features.filter(tag => currentMetrics.features.includes(tag)) : [...features])
+      : [];
+    const featureSettings = activeFeatures.length > 0 ? buildFontFeatureSettings(activeFeatures) : undefined;
+
     return {
-      // Font family from the theme (e.g. 'default' → 'Inter', 'mono' → 'JetBrains Mono').
-      fontFamily: tokens.typography.fonts[font],
-      fontSize,
-      // Font weight is stored as a number (e.g. 400, 600) but React Native expects a string.
-      fontWeight: String(tokens.typography.weight[weight]) as TextStyle['fontWeight'],
-      // Convert the theme color from internal sRGB format to a hex string (e.g. '#1a1a1a').
+      fontFamily: fontSlot.family,
+      fontSize: activeStep.fontSize,
+      fontWeight: String(resolvedFontWeight) as TextStyle['fontWeight'],
       color: resolveTextColor(color, tokens),
-      // Line height = font size × multiplier (e.g. 16px × 1.5 = 24px line height).
-      lineHeight: fontSize * tokens.typography.lineHeight[lineHeight],
+      lineHeight: correctedLineHeight,
       textAlign: align,
+      ...(vcOffset !== 0 ? { transform: [{ translateY: vcOffset }] } : {}),
+      ...(featureSettings ? { fontFeatureSettings: featureSettings } as any : {}),
     };
-  }, [tokens, size, weight, color, font, lineHeight, align]);
-
-  return (
-    <RNText
-      ref={ref}
-      testID={testID}
-      nativeID={nativeID}
-      accessibilityRole={accessibilityRole}
-      // If the user passed custom styles, merge them after the theme styles.
-      // The last style in the array wins, so user styles can override theme defaults.
-      // Normalize: the user can pass a single style or an array of styles.
-      style={style
-        ? [resolvedStyle, ...(Array.isArray(style) ? style : [style])]
-        : resolvedStyle
-      }
-      // When set, text is cut off after this many lines with "..." at the end.
-      numberOfLines={numberOfLines}
-    >
-      {children}
-    </RNText>
+  }, [tokens, fontSlot, step, resolvedStep, responsive, isAdaptive, resolvedFontWeight, color, align, config.typography.fontMetrics, centerVertically, features]);
+
+  // Auto-derive accessibility role and heading level for heading-like typography roles.
+  // react-native-web uses aria-level to render the correct <h1>/<h2>/<h3> element.
+  const inferredA11yRole = (role === 'headline' || role === 'title' || role === 'heading')
+    ? 'header' as const
+    : undefined;
+  const effectiveA11yRole = accessibilityRoleOverride ?? inferredA11yRole;
+  const ariaLevel = effectiveA11yRole === 'header' ? ROLE_HEADING_LEVEL[role] : undefined;
+
+  // Scope context value for span sub-components (stable reference — weights are constant)
+  const scopeCtx = useMemo(() => ({ weights: SEMANTIC_WEIGHT_MAP }), []);
+
+  const textNode = (
+    <TextScopeContext.Provider value={scopeCtx}>
+      <RNText
+        ref={ref}
+        testID={testID}
+        nativeID={nativeID}
+        accessibilityRole={effectiveA11yRole}
+        aria-level={ariaLevel}
+        style={style
+          ? [resolvedStyle, ...(Array.isArray(style) ? style : [style])]
+          : resolvedStyle
+        }
+        numberOfLines={numberOfLines}
+      >
+        {children}
+      </RNText>
+    </TextScopeContext.Provider>
   );
+
+  // Wrap in a View for container measurement when responsive mode is active on an adaptive role.
+  // onLayout fires whenever the container's dimensions change, providing the measured width.
+  if (responsive && isAdaptive) {
+    return (
+      <View
+        onLayout={(e: LayoutChangeEvent) => {
+          const w = e.nativeEvent.layout.width;
+          if (w > 0) setContainerWidth(w);
+        }}
+        style={{ width: '100%' }}
+      >
+        {textNode}
+      </View>
+    );
+  }
+
+  return textNode;
 }
+
+export { TextBase };