@newtonedev/components 0.1.6 → 0.1.8

package/src/fonts/measureFont.ts

@@ -0,0 +1,42 @@
+/**
+ * Reference string for character width measurement.
+ * Covers uppercase, lowercase, digits, and a space — 63 characters total.
+ */
+const REF_STRING =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 ';
+
+/**
+ * Measure the average character width ratio for a font using the Canvas API.
+ *
+ * Waits for the font to load via `document.fonts.load()` before measuring.
+ * Falls back to 0.55 if the browser context is unavailable, the font fails
+ * to load, or canvas is not supported.
+ *
+ * The returned ratio represents `avgCharWidth / fontSize`. Multiply by a
+ * desired fontSize to estimate character widths for that font.
+ *
+ * @param fontFamily - Font family name, e.g. "Inter" or "system-ui"
+ * @param fontWeight - CSS font-weight number, e.g. 400
+ * @param fallback   - CSS fallback stack, e.g. "sans-serif"
+ * @param fontSize   - Reference font size in px (default 16)
+ * @returns Average character width ratio, e.g. 0.52 for Inter
+ */
+export async function measureAvgCharWidth(
+  fontFamily: string,
+  fontWeight: number,
+  fallback: string,
+  fontSize = 16,
+): Promise<number> {
+  if (typeof document === 'undefined') return 0.55;
+  try {
+    await document.fonts.load(`${fontWeight} ${fontSize}px "${fontFamily}"`);
+    const canvas = document.createElement('canvas');
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return 0.55;
+    ctx.font = `${fontWeight} ${fontSize}px "${fontFamily}", ${fallback}`;
+    const ratio = ctx.measureText(REF_STRING).width / REF_STRING.length / fontSize;
+    return Math.round(ratio * 1000) / 1000;
+  } catch {
+    return 0.55;
+  }
+}

package/src/fonts/reportQueue.ts

@@ -0,0 +1,54 @@
+import type { ObserverPayload } from '@newtonedev/fonts';
+
+/**
+ * Module-level batch queue for typography observations (Layer 3 reporting).
+ *
+ * Lives outside React's component lifecycle so it survives re-renders.
+ * Observations are enqueued immediately and flushed in a single batch after
+ * a 2s debounce — minimising network requests and allowing coalescence.
+ *
+ * Usage: call `enqueueObservation(endpoint, payload)` from responsive Text
+ * instances. Set `reportingEndpoint` on `NewtoneProvider` to opt in.
+ */
+
+interface QueuedObservation {
+  readonly endpoint: string;
+  readonly payload: ObserverPayload;
+}
+
+const queue: QueuedObservation[] = [];
+let flushTimer: ReturnType<typeof setTimeout> | undefined;
+
+function flush(): void {
+  if (queue.length === 0) return;
+
+  // Group by endpoint so a page with multiple endpoints gets one request each
+  const byEndpoint = new Map<string, ObserverPayload[]>();
+  for (const item of queue) {
+    const group = byEndpoint.get(item.endpoint) ?? [];
+    group.push(item.payload);
+    byEndpoint.set(item.endpoint, group);
+  }
+  queue.length = 0;
+
+  for (const [endpoint, observations] of byEndpoint) {
+    // Fire-and-forget — reporting failures are silent and never affect the UI
+    fetch(endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ observations }),
+      // keepalive: true allows the request to outlive the page
+      keepalive: true,
+    }).catch(() => {});
+  }
+}
+
+/**
+ * Enqueue a typography observation for batch reporting.
+ * Resets the 2s debounce timer on each call.
+ */
+export function enqueueObservation(endpoint: string, payload: ObserverPayload): void {
+  queue.push({ endpoint, payload });
+  if (flushTimer !== undefined) clearTimeout(flushTimer);
+  flushTimer = setTimeout(flush, 2000);
+}

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';
@@ -115,6 +123,7 @@ export type {
   EditableProp,
   EditablePropOption,
   ComponentMeta,
+  IconCatalogCategory,
 } from './registry';
 export {
   CATEGORIES,
@@ -123,12 +132,14 @@ export {
   getCategory,
   getComponentsByCategory,
   generateComponentCode,
+  ICON_CATALOG,
 } 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

@@ -23,9 +23,7 @@ export function Icon({
   opticalSize,
   fill = 0,
   color,
-  elevation = 1,
   style,
-  onPress,
   // Accessibility
   accessibilityLabel,
   // Testing & platform
@@ -33,15 +31,15 @@ export function Icon({
   nativeID,
   ref,
 }: IconProps) {
-  // Get the current theme's design tokens for colors, typography, and icon settings.
-  const tokens = useTokens(elevation);
+  // Inherit tokens from nearest parent Frame via FrameContext.
+  const tokens = useTokens();
 
   // Build the icon's style from the theme tokens and props.
   // Wrapped in useMemo so it only recalculates when the inputs change,
   // 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.
@@ -69,7 +67,8 @@ export function Icon({
     //   wght: font weight (thinner or bolder strokes)
     //   GRAD: grade (fine-tune weight without changing overall size)
     //   opsz: optical size (adjusts detail level for the display size)
-    const fontVariationSettings = `'FILL' ${fill}, 'wght' ${tokens.icons.weight}, 'GRAD' ${tokens.icons.grade}, 'opsz' ${opsz}`;
+    const fillValue = typeof fill === 'boolean' ? (fill ? 1 : 0) : fill;
+    const fontVariationSettings = `'FILL' ${fillValue}, 'wght' ${tokens.icons.weight}, 'GRAD' ${tokens.icons.grade}, 'opsz' ${opsz}`;
 
     return {
       fontFamily,
@@ -96,7 +95,6 @@ export function Icon({
       // so assistive technology doesn't try to read the ligature text (e.g. "home").
       importantForAccessibility={accessibilityLabel ? 'yes' : 'no-hide-descendants'}
       style={iconStyle}
-      onPress={onPress} // When provided, makes the icon tappable
     >
       {name}
     </Text>

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

@@ -1,18 +1,17 @@
 import type { Text as RNText, TextStyle } from 'react-native';
-import type { ElevationLevel } from '../../theme/types';
 
 /**
  * Props for Icon — Material Symbols icon with variable font support.
  *
- * Uses the icon variant, weight, and grade from the theme config.
- * Per-instance control over size, fill, and color.
+ * Icon is a pure presentation primitive. It inherits elevation from the
+ * nearest parent Frame via FrameContext. For interactive icons, wrap in
+ * `<Button icon="..." />` instead.
  *
  * @example
  * ```tsx
  * <Icon name="home" />
  * <Icon name="settings" size={24} fill={1} />
  * <Icon name="check" color="#00ff00" />
- * <Icon name="delete" size={20} onPress={() => handleDelete()} />
  * ```
  *
  * @see {@link https://fonts.google.com/icons Material Symbols icon reference}
@@ -26,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 */
@@ -35,23 +34,17 @@ export interface IconProps {
   /**
    * Fill state for the icon.
    *
-   * - `0` — Outlined (default)
-   * - `1` — Filled (solid)
+   * - `false` / `0` — Outlined (default)
+   * - `true` / `1` — Filled (solid)
    */
-  readonly fill?: 0 | 1;
+  readonly fill?: boolean | 0 | 1;
 
   /** Icon color as hex string. @default tokens.textPrimary */
   readonly color?: string;
 
-  /** Elevation level for token computation. @default 1 */
-  readonly elevation?: ElevationLevel;
-
-  /** Additional styles applied to the icon Text element. */
+  /** Additional styles applied to the icon Text element (positioning, transforms). */
   readonly style?: TextStyle;
 
-  /** Press handler — makes the icon tappable. */
-  readonly onPress?: () => void;
-
   // ── Accessibility ──
 
   /** Label read by screen readers. When omitted, the icon is treated as decorative (hidden from assistive technology). */

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);
+}