@newtonedev/components 0.1.7 → 0.1.9

package/src/primitives/Text/Text.types.ts

@@ -1,20 +1,25 @@
 import type { Text as RNText, TextStyle } from 'react-native';
 import type { ElevationLevel } from '../../theme/types';
 
-/** Typography size tokens — maps to `tokens.typography.size.*` pixel values. */
-export type TextSize = 'xs' | 'sm' | 'base' | 'md' | 'lg' | 'xl' | 'xxl';
+/** Typography size step — selects within the current role's 3-step scale. @default 'md' */
+export type TextSize = 'sm' | 'md' | 'lg';
 
-/** Typography weight tokens — maps to `tokens.typography.weight.*` numeric values. */
-export type TextWeight = 'regular' | 'medium' | 'semibold' | 'bold';
+/** Font weight slots — maps to per-scope `tokens.typography.fonts[scope].weights.*` values. */
+export type TextWeight = 'regular' | 'medium' | 'bold';
 
 /** Semantic text color tokens — resolved from the current theme's token palette. */
 export type TextColor = 'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'warning' | 'error';
 
-/** Font family tokens — maps to `tokens.typography.fonts.*` font stacks. */
-export type TextFont = 'default' | 'display' | 'mono';
+/** Font scope — selects which font family slot to use. @default 'main' */
+export type TextScope = 'main' | 'display' | 'mono' | 'currency';
 
-/** Line height multiplier tokens — maps to `tokens.typography.lineHeight.*` values. */
-export type TextLineHeight = 'tight' | 'normal' | 'relaxed';
+/**
+ * Semantic text role — determines default size, weight, and line height.
+ * Provides purpose-driven typography presets. Individual size/weight/lineHeight
+ * props can override the role's defaults when needed (e.g., in composites).
+ * @default 'body'
+ */
+export type TextRole = 'headline' | 'title' | 'heading' | 'subheading' | 'body' | 'label' | 'caption';
 
 /** Text alignment. */
 export type TextAlign = 'left' | 'center' | 'right';
@@ -22,38 +27,37 @@ export type TextAlign = 'left' | 'center' | 'right';
 /**
  * Props for Text — themed typography component.
  *
- * All visual properties are token-driven: size, weight, color, font,
- * and line height resolve from the current theme context. Use semantic
- * tokens rather than raw values for consistency.
+ * Primary API surface: `scope` (font family) + `role` (semantic preset) + `color`.
+ * Individual size/weight/lineHeight props are available as overrides for composites.
  *
  * @example
  * ```tsx
  * <Text>Default body text</Text>
- * <Text size="lg" weight="bold">Heading</Text>
- * <Text color="secondary" size="sm">Caption text</Text>
- * <Text font="mono" size="sm">const x = 42;</Text>
- * <Text numberOfLines={2}>Long text that truncates after two lines...</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 with <Text.Bold>bold emphasis</Text.Bold></Text>
  * ```
  */
 export interface TextProps {
   /**
-   * Text content. Accepts strings, numbers, and nested `<Text>` elements
-   * for inline formatting (e.g., bold spans within a paragraph).
+   * Text content. Accepts strings, numbers, and span sub-components
+   * for inline formatting (e.g., `<Text.Bold>`, `<Text.Italic>`).
    *
    * @example
    * ```tsx
    * <Text>Plain string</Text>
    * <Text>Count: {42}</Text>
-   * <Text>Normal <Text weight="bold">bold</Text> normal</Text>
+   * <Text role="body">Normal <Text.Bold>bold</Text.Bold> normal</Text>
    * ```
    */
   readonly children: React.ReactNode;
 
-  /** Typography size token. @default 'base' */
-  readonly size?: TextSize;
+  /** Font scope — selects which font family to use. @default 'main' */
+  readonly scope?: TextScope;
 
-  /** Font weight token. @default 'regular' */
-  readonly weight?: TextWeight;
+  /** Semantic role — sets default size/weight/lineHeight. @default 'body' */
+  readonly role?: TextRole;
 
   /**
    * Semantic color token.
@@ -71,11 +75,13 @@ export interface TextProps {
    */
   readonly color?: TextColor;
 
-  /** Font family token. @default 'default' */
-  readonly font?: TextFont;
+  // ── Overrides (used by composites, not exposed in editor UI) ──
+
+  /** Override the role's default size. */
+  readonly size?: TextSize;
 
-  /** Line height multiplier token. @default 'normal' */
-  readonly lineHeight?: TextLineHeight;
+  /** Override the role's default weight. */
+  readonly weight?: TextWeight;
 
   /** Text alignment. */
   readonly align?: TextAlign;
@@ -92,7 +98,8 @@ export interface TextProps {
   // ── Accessibility ──
 
   /**
-   * Semantic role for screen readers.
+   * Semantic role for screen readers. Auto-inferred from typography role
+   * (headline/title/heading → 'header') unless explicitly set.
    *
    * - `'header'` — Marks this as a heading (e.g. page title, section header)
    * - `'text'` — Default text role (usually omitted)
@@ -110,4 +117,53 @@ export interface TextProps {
 
   /** Ref to the underlying React Native Text element. */
   readonly ref?: React.Ref<RNText>;
+
+  /**
+   * Enable responsive font sizing for adaptive roles (headline, title, heading, subheading).
+   * When true, the Text component measures its container width and uses `resolveResponsiveSize`
+   * to pick the best fontSize within the role's natural size, improving line-break quality.
+   * Requires the text to be wrapped in a container that defines a width.
+   * No-op for non-adaptive roles (body, label, caption).
+   * @default false
+   */
+  readonly responsive?: boolean;
+
+  /**
+   * Apply vertical centering correction to compensate for font metrics.
+   * Shifts text down by the font's verticalCenterOffset so that cap-height
+   * text appears visually centered within flex containers (buttons, chips).
+   * No-op for multi-line body text — only enable in single-line centering contexts.
+   * Requires fontMetrics in the theme config; ignored when metrics are unavailable.
+   * @default false
+   */
+  readonly centerVertically?: boolean;
+
+  /**
+   * OpenType feature tags to enable (e.g., `['tnum', 'kern']`).
+   * When fontMetrics are available, requested tags are filtered against the font's
+   * supported features. When metrics are unavailable, all tags are applied optimistically.
+   * Maps to the CSS `font-feature-settings` property via react-native-web.
+   */
+  readonly features?: readonly string[];
+}
+
+/**
+ * Constrained props for inline span sub-components (Text.Bold, Text.Italic, etc.).
+ * Spans inherit font family, size, and line height from the parent Text.
+ * Only inline formatting properties are exposed.
+ */
+export interface TextSpanProps {
+  readonly children: React.ReactNode;
+  /** Override text color within the span. */
+  readonly color?: TextColor;
+  /** Override font weight within the span. */
+  readonly weight?: TextWeight;
+  /** Apply italic style. */
+  readonly italic?: boolean;
+  /** Apply underline decoration. */
+  readonly underline?: boolean;
+  /** Apply background highlight using a semantic color token. */
+  readonly highlight?: TextColor;
+  /** Style overrides (applied last). */
+  readonly style?: TextStyle | readonly TextStyle[];
 }

package/src/primitives/Text/index.ts

@@ -1,10 +1,34 @@
-export { Text } from './Text';
+import { TextBase } from './Text';
+import { TextSpan, TextBold, TextMedium, TextItalic, TextUnderline, TextHighlight } from './Text.spans';
+
+/**
+ * Token-aware text primitive with span sub-components.
+ *
+ * Primary API: `scope` (font family) + `role` (semantic preset) + `color`.
+ *
+ * @example
+ * ```tsx
+ * <Text role="headline" scope="display">Hero</Text>
+ * <Text role="body">Regular <Text.Bold>bold</Text.Bold> text</Text>
+ * <Text role="label" color="secondary">Field label</Text>
+ * ```
+ */
+export const Text = Object.assign(TextBase, {
+  Span: TextSpan,
+  Bold: TextBold,
+  Medium: TextMedium,
+  Italic: TextItalic,
+  Underline: TextUnderline,
+  Highlight: TextHighlight,
+});
+
 export type {
   TextProps,
   TextSize,
   TextWeight,
   TextColor,
-  TextFont,
-  TextLineHeight,
+  TextScope,
+  TextRole,
   TextAlign,
+  TextSpanProps,
 } from './Text.types';

package/src/primitives/index.ts

@@ -40,7 +40,8 @@ export type {
   TextSize,
   TextWeight,
   TextColor,
-  TextFont,
-  TextLineHeight,
+  TextScope,
+  TextRole,
+  TextSpanProps,
   TextAlign,
 } from './Text';

package/src/registry/codegen.ts

@@ -18,6 +18,7 @@ const HANDLER_PROPS: Record<string, readonly string[]> = {
  */
 const CHILDREN_CONTENT: Record<string, string> = {
   button: 'Button',
+  text: 'The quick brown fox',
   card: '{/* content */}',
   frame: '{/* content */}',
 };

package/src/registry/registry.ts

@@ -1,12 +1,11 @@
 import type { CategoryMeta, ComponentMeta } from './types';
 
 export const CATEGORIES: readonly CategoryMeta[] = [
-  { id: 'primitives', name: 'Design Primitives', description: 'Core building blocks for theme-aware layouts and typography' },
-  { id: 'actions', name: 'Actions', description: 'Interactive elements that trigger actions' },
-  { id: 'form-controls', name: 'Form Controls', description: 'Input elements for user data entry' },
-  { id: 'range-inputs', name: 'Range Inputs', description: 'Slider controls for numeric and continuous values' },
-  { id: 'layout', name: 'Layout', description: 'Structural and container components' },
-  { id: 'overlays', name: 'Overlays', description: 'Floating and portal-based UI elements' },
+  { id: 'colors', name: 'Colors', description: 'Color palettes and token visualization', icon: 'palette' },
+  { id: 'typography', name: 'Typography', description: 'Text roles, scopes, and weight control', icon: 'text_fields' },
+  { id: 'symbols', name: 'Symbols', description: 'Material Symbols icon browser', icon: 'grid_view' },
+  { id: 'layout', name: 'Layout', description: 'Structural containers — Frame and Wrapper', icon: 'grid_on' },
+  { id: 'components', name: 'Components', description: 'Interactive UI components', icon: 'widgets' },
 ];
 
 export const COMPONENTS: readonly ComponentMeta[] = [
@@ -14,7 +13,7 @@ export const COMPONENTS: readonly ComponentMeta[] = [
     id: 'button',
     name: 'Button',
     importName: 'Button',
-    categoryId: 'actions',
+    categoryId: 'components',
     description: 'Interactive button with multiple variants, sizes, and optional icon',
     hasChildren: true,
     variants: [
@@ -96,7 +95,7 @@ export const COMPONENTS: readonly ComponentMeta[] = [
     id: 'text-input',
     name: 'TextInput',
     importName: 'TextInput',
-    categoryId: 'form-controls',
+    categoryId: 'components',
     description: 'Text input field with label support',
     hasChildren: false,
     variants: [
@@ -123,7 +122,7 @@ export const COMPONENTS: readonly ComponentMeta[] = [
     id: 'select',
     name: 'Select',
     importName: 'Select',
-    categoryId: 'form-controls',
+    categoryId: 'components',
     description: 'Dropdown selector with options',
     hasChildren: false,
     variants: [
@@ -170,7 +169,7 @@ export const COMPONENTS: readonly ComponentMeta[] = [
     id: 'toggle',
     name: 'Toggle',
     importName: 'Toggle',
-    categoryId: 'form-controls',
+    categoryId: 'components',
     description: 'Binary switch component',
     hasChildren: false,
     variants: [
@@ -197,7 +196,7 @@ export const COMPONENTS: readonly ComponentMeta[] = [
     id: 'slider',
     name: 'Slider',
     importName: 'Slider',
-    categoryId: 'range-inputs',
+    categoryId: 'components',
     description: 'Numeric range slider',
     hasChildren: false,
     variants: [
@@ -241,7 +240,7 @@ export const COMPONENTS: readonly ComponentMeta[] = [
     id: 'hue-slider',
     name: 'HueSlider',
     importName: 'HueSlider',
-    categoryId: 'range-inputs',
+    categoryId: 'components',
     description: 'Specialized slider for hue selection (0-360\u00b0)',
     hasChildren: false,
     variants: [
@@ -377,7 +376,7 @@ export const COMPONENTS: readonly ComponentMeta[] = [
     id: 'card',
     name: 'Card',
     importName: 'Card',
-    categoryId: 'layout',
+    categoryId: 'components',
     description: 'Surface container with elevation levels',
     hasChildren: true,
     variants: [
@@ -410,45 +409,59 @@ export const COMPONENTS: readonly ComponentMeta[] = [
     id: 'text',
     name: 'Text',
     importName: 'Text',
-    categoryId: 'primitives',
-    description: 'Typography primitive with semantic size, weight, color, font, and lineHeight',
+    categoryId: 'typography',
+    description: 'Typography primitive with semantic scope (font family) and role (purpose)',
     hasChildren: true,
+    previewLayout: 'list',
     variants: [
-      { id: 'default', label: 'Default', props: {} },
-      { id: 'heading', label: 'Heading', props: { size: 'xl', weight: 'bold' } },
-      { id: 'subheading', label: 'Subheading', props: { size: 'lg', weight: 'semibold' } },
-      { id: 'body', label: 'Body', props: { size: 'base' } },
-      { id: 'caption', label: 'Caption', props: { size: 'sm', color: 'secondary' } },
-      { id: 'accent', label: 'Accent', props: { color: 'accent', weight: 'medium' } },
-      { id: 'mono', label: 'Monospace', props: { font: 'mono', size: 'sm' } },
+      { id: 'body', label: 'Body', props: { role: 'body' } },
+      { id: 'headline', label: 'Headline', props: { role: 'headline', scope: 'display' } },
+      { id: 'title', label: 'Title', props: { role: 'title', scope: 'display' } },
+      { id: 'heading', label: 'Heading', props: { role: 'heading' } },
+      { id: 'subheading', label: 'Subheading', props: { role: 'subheading' } },
+      { id: 'label', label: 'Label', props: { role: 'label' } },
+      { id: 'caption', label: 'Caption', props: { role: 'caption', color: 'secondary' } },
+      { id: 'mono', label: 'Monospace', props: { scope: 'mono', role: 'body' } },
+      { id: 'currency', label: 'Currency', props: { scope: 'currency', role: 'body' } },
     ],
     editableProps: [
       {
-        name: 'size',
-        label: 'Size',
+        name: 'scope',
+        label: 'Scope',
         control: 'select',
         options: [
-          { label: 'Extra Small', value: 'xs' },
-          { label: 'Small', value: 'sm' },
-          { label: 'Base', value: 'base' },
-          { label: 'Medium', value: 'md' },
-          { label: 'Large', value: 'lg' },
-          { label: 'Extra Large', value: 'xl' },
-          { label: 'XXL', value: 'xxl' },
+          { label: 'Main', value: 'main' },
+          { label: 'Display', value: 'display' },
+          { label: 'Mono', value: 'mono' },
+          { label: 'Currency', value: 'currency' },
         ],
-        defaultValue: 'base',
+        defaultValue: 'main',
       },
       {
-        name: 'weight',
-        label: 'Weight',
+        name: 'role',
+        label: 'Role',
         control: 'select',
         options: [
-          { label: 'Regular', value: 'regular' },
-          { label: 'Medium', value: 'medium' },
-          { label: 'Semibold', value: 'semibold' },
-          { label: 'Bold', value: 'bold' },
+          { label: 'Headline', value: 'headline' },
+          { label: 'Title', value: 'title' },
+          { label: 'Heading', value: 'heading' },
+          { label: 'Subheading', value: 'subheading' },
+          { label: 'Body', value: 'body' },
+          { label: 'Label', value: 'label' },
+          { label: 'Caption', value: 'caption' },
         ],
-        defaultValue: 'regular',
+        defaultValue: 'body',
+      },
+      {
+        name: 'size',
+        label: 'Size',
+        control: 'select',
+        options: [
+          { label: 'Small', value: 'sm' },
+          { label: 'Medium', value: 'md' },
+          { label: 'Large', value: 'lg' },
+        ],
+        defaultValue: 'md',
       },
       {
         name: 'color',
@@ -466,24 +479,13 @@ export const COMPONENTS: readonly ComponentMeta[] = [
         ],
         defaultValue: 'primary',
       },
-      {
-        name: 'font',
-        label: 'Font',
-        control: 'select',
-        options: [
-          { label: 'Default', value: 'default' },
-          { label: 'Display', value: 'display' },
-          { label: 'Mono', value: 'mono' },
-        ],
-        defaultValue: 'default',
-      },
     ],
   },
   {
     id: 'icon',
     name: 'Icon',
     importName: 'Icon',
-    categoryId: 'primitives',
+    categoryId: 'symbols',
     description: 'Material Symbols icon with size and fill',
     hasChildren: false,
     variants: [
@@ -520,7 +522,7 @@ export const COMPONENTS: readonly ComponentMeta[] = [
     id: 'wrapper',
     name: 'Wrapper',
     importName: 'Wrapper',
-    categoryId: 'primitives',
+    categoryId: 'layout',
     description: 'Lightweight layout container with direction, spacing, and alignment (no theming)',
     hasChildren: true,
     variants: [
@@ -594,7 +596,7 @@ export const COMPONENTS: readonly ComponentMeta[] = [
     id: 'color-scale-slider',
     name: 'ColorScaleSlider',
     importName: 'ColorScaleSlider',
-    categoryId: 'range-inputs',
+    categoryId: 'components',
     description: 'Interactive palette preview slider with color segments',
     hasChildren: false,
     variants: [

package/src/registry/types.ts

@@ -2,6 +2,7 @@ export interface CategoryMeta {
   readonly id: string;
   readonly name: string;
   readonly description: string;
+  readonly icon?: string;
 }
 
 export interface VariantMeta {
@@ -30,6 +31,7 @@ export interface ComponentMeta {
   readonly categoryId: string;
   readonly description: string;
   readonly hasChildren: boolean;
+  readonly previewLayout?: 'grid' | 'list';
   readonly variants: readonly VariantMeta[];
   readonly editableProps: readonly EditableProp[];
 }

package/src/theme/NewtoneProvider.tsx

@@ -2,6 +2,7 @@ import React, { createContext, useState, useMemo, useContext } from 'react';
 import type { NewtoneThemeConfig, NewtoneThemeContext, ColorMode } from './types';
 import { DEFAULT_THEME_CONFIG } from './defaults';
 import { GoogleFontLoader } from '../fonts/GoogleFontLoader';
+import { SelfHostedFontLoader } from '../fonts/SelfHostedFontLoader';
 import { IconFontLoader } from '../fonts/IconFontLoader';
 
 const ThemeContext = createContext<NewtoneThemeContext | null>(null);
@@ -10,6 +11,14 @@ export interface NewtoneProviderProps {
   readonly config?: NewtoneThemeConfig;
   readonly initialMode?: ColorMode;
   readonly children: React.ReactNode;
+  /** Optional URL for typography telemetry. When set, adaptive Text instances report observations. */
+  readonly reportingEndpoint?: string;
+  /**
+   * Self-hosted @font-face CSS from the theme API.
+   * When provided, injects this CSS instead of loading from Google CDN.
+   * Falls back to Google CDN when absent or null.
+   */
+  readonly fontFaceCss?: string | null;
 }
 
 /**
@@ -28,6 +37,8 @@ export function NewtoneProvider({
   config = DEFAULT_THEME_CONFIG,
   initialMode = 'light',
   children,
+  reportingEndpoint,
+  fontFaceCss,
 }: NewtoneProviderProps) {
   const [mode, setMode] = useState<ColorMode>(initialMode);
 
@@ -36,13 +47,18 @@ export function NewtoneProvider({
       config,
       mode,
       setMode,
+      reportingEndpoint,
     }),
-    [config, mode]
+    [config, mode, reportingEndpoint]
   );
 
   return (
     <ThemeContext.Provider value={value}>
-      <GoogleFontLoader fonts={config.typography.fonts} />
+      {fontFaceCss ? (
+        <SelfHostedFontLoader fontFaceCss={fontFaceCss} />
+      ) : (
+        <GoogleFontLoader fonts={config.typography.fonts} />
+      )}
       <IconFontLoader icons={config.icons} />
       {children}
     </ThemeContext.Provider>

package/src/theme/defaults.ts

@@ -11,6 +11,10 @@ import {
   DEFAULT_ERROR_HUE,
   DEFAULT_ERROR_SATURATION,
 } from 'newtone';
+import { DEFAULT_FONT_SLOTS, DEFAULT_FONT_SIZES, DEFAULT_LINE_HEIGHTS, DEFAULT_ROLE_SCALES } from '@newtonedev/fonts';
+
+// Re-export typography defaults from @newtonedev/fonts (canonical source)
+export { DEFAULT_FONT_SIZES, DEFAULT_LINE_HEIGHTS, DEFAULT_ROLE_SCALES } from '@newtonedev/fonts';
 
 /**
  * Default theme configuration matching playground defaults.
@@ -54,34 +58,10 @@ export const DEFAULT_THEME_CONFIG: NewtoneThemeConfig = {
     pill: 999,
   },
   typography: {
-    fonts: {
-      mono: {
-        type: 'system',
-        family: 'ui-monospace',
-        fallback: 'SFMono-Regular, Menlo, Monaco, Consolas, monospace',
-      },
-      display: {
-        type: 'system',
-        family: 'system-ui',
-        fallback: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
-      },
-      default: {
-        type: 'system',
-        family: 'system-ui',
-        fallback: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
-      },
-    },
-    scale: {
-      xs: 10,   // 16 / 1.25^2
-      sm: 13,   // 16 / 1.25
-      base: 16,
-      md: 20,   // 16 * 1.25
-      lg: 25,   // 16 * 1.25^2
-      xl: 31,   // 16 * 1.25^3
-      xxl: 39,  // 16 * 1.25^4
-    },
-    lineHeight: { tight: 1.25, normal: 1.5, relaxed: 1.75 },
-    fontWeight: { regular: 400, medium: 500, semibold: 600, bold: 700 },
+    fonts: DEFAULT_FONT_SLOTS,
+    fontSizes: DEFAULT_FONT_SIZES,
+    lineHeights: DEFAULT_LINE_HEIGHTS,
+    roles: DEFAULT_ROLE_SCALES,
   },
   icons: {
     variant: 'rounded',  // Material Design 3 aesthetic