@newtonedev/components 0.1.13 → 0.1.14

package/src/primitives/Frame/Frame.types.ts

@@ -1,5 +1,5 @@
 import type { View, ViewStyle, GestureResponderEvent } from 'react-native';
-import type { FrameElevation } from 'newtone-api';
+import type { FrameElevation, ThemeName, AppearanceName } from 'newtone-api';
 
 // ── Spacing Types ──────────────────────────────────────────────
 
@@ -76,6 +76,20 @@ export interface RadiusCorners {
  */
 export type RadiusProp = RadiusValue | RadiusCorners;
 
+// ── Positioning Types ──────────────────────────────────────────
+
+/** CSS position mode. `'fixed'` and `'sticky'` are web-only (via react-native-web). */
+export type PositionType = 'absolute' | 'relative' | 'fixed' | 'sticky';
+
+/** Position offset value: pixels (number) or percentage string (e.g. `'50%'`). */
+export type OffsetValue = number | string;
+
+/** Overflow clipping mode. */
+export type OverflowMode = 'visible' | 'hidden' | 'scroll';
+
+/** Pointer-events mode (View prop, not a style). */
+export type PointerEventsMode = 'auto' | 'none' | 'box-none' | 'box-only';
+
 // ── Sizing Types ───────────────────────────────────────────────
 
 /**
@@ -159,6 +173,23 @@ export interface FrameProps {
    */
   readonly elevation?: FrameElevation;
 
+  /**
+   * Named scheme to use for this Frame's subtree.
+   * Looks up the scheme's config from the ancestor NewtoneProvider's `schemes` map
+   * and uses it instead of the default for token computation and context.
+   * Ignored when the provider is in single-config mode.
+   *
+   * @example
+   * ```tsx
+   * <NewtoneProvider schemes={{ Default: config1, Dark: config2 }} defaultScheme="Default">
+   *   <Frame scheme="Dark">
+   *     {/* Children here get the "Dark" scheme's tokens *​/}
+   *   </Frame>
+   * </NewtoneProvider>
+   * ```
+   */
+  readonly scheme?: string;
+
   // ── Layout ──
 
   /** Layout mode. @default 'flex' */
@@ -248,8 +279,95 @@ export interface FrameProps {
   /** Maximum height in pixels. */
   readonly maxHeight?: number;
 
+  // ── Positioning ──
+
+  /**
+   * CSS position mode.
+   *
+   * `'fixed'` and `'sticky'` are web-only (supported via react-native-web).
+   * React Native natively supports `'absolute'` and `'relative'`.
+   */
+  readonly position?: PositionType;
+
+  /** Offset from the top edge. Accepts pixels (number) or percentage string. */
+  readonly top?: OffsetValue;
+
+  /** Offset from the right edge. Accepts pixels (number) or percentage string. */
+  readonly right?: OffsetValue;
+
+  /** Offset from the bottom edge. Accepts pixels (number) or percentage string. */
+  readonly bottom?: OffsetValue;
+
+  /** Offset from the left edge. Accepts pixels (number) or percentage string. */
+  readonly left?: OffsetValue;
+
+  /** Stacking order. Higher values render above lower values. */
+  readonly zIndex?: number;
+
+  /**
+   * Content overflow behavior.
+   *
+   * When `radius` is set with positive values, Frame auto-applies `overflow: 'hidden'`
+   * to clip content at rounded corners. Setting `overflow` explicitly overrides this.
+   */
+  readonly overflow?: OverflowMode;
+
+  /**
+   * Controls whether the element can be the target of touch/pointer events.
+   *
+   * - `'auto'` — default, element and children receive events
+   * - `'none'` — element and children are invisible to events (pass through)
+   * - `'box-none'` — element ignores events but children can receive them
+   * - `'box-only'` — element receives events but children cannot
+   */
+  readonly pointerEvents?: PointerEventsMode;
+
+  /**
+   * Opacity of the element (0 = fully transparent, 1 = fully opaque).
+   *
+   * When set explicitly, overrides the automatic `0.5` opacity applied by `disabled`.
+   */
+  readonly opacity?: number;
+
   // ── Appearance ──
 
+  /**
+   * Color theme for this Frame's visual rendering (background, border, text).
+   *
+   * Selects which of the 6 themes to use from the resolved tokens.
+   * Does not affect scheme selection — use `scheme` for that.
+   *
+   * @default 'primary'
+   *
+   * @example
+   * ```tsx
+   * <Frame theme="error" appearance="tinted">
+   *   <Text>Error banner</Text>
+   * </Frame>
+   * ```
+   */
+  readonly theme?: ThemeName;
+
+  /**
+   * Appearance variant within the selected theme.
+   *
+   * Controls the visual emphasis of the Frame's chrome (background, border):
+   * - `'main'` — default surface (passive contrast)
+   * - `'emphasis'` — prominent, filled surface (active contrast)
+   * - `'tinted'` — subtle tinted surface
+   * - `'strong'` — bold, high-contrast variant
+   *
+   * @default 'main'
+   *
+   * @example
+   * ```tsx
+   * <Frame theme="primary" appearance="emphasis">
+   *   <Text>CTA section</Text>
+   * </Frame>
+   * ```
+   */
+  readonly appearance?: AppearanceName;
+
   /**
    * Border radius.
    *

package/src/primitives/Frame/index.ts

@@ -17,5 +17,9 @@ export type {
   Direction,
   Alignment,
   Justification,
+  PositionType,
+  OffsetValue,
+  OverflowMode,
+  PointerEventsMode,
 } from './Frame.types';
 export type { ResolvedCorners } from './Frame.utils';

package/src/primitives/Icon/Icon.tsx

@@ -1,6 +1,6 @@
 import React, { useMemo } from 'react';
 import { Text, type TextStyle } from 'react-native';
-import { useTokens } from 'newtone-api';
+import { useTokens, useFrameContext } from 'newtone-api';
 import type { IconProps } from './Icon.types';
 
 /**
@@ -17,8 +17,8 @@ import type { IconProps } from './Icon.types';
  * ```
  */
 export function Icon({
-  name,
-  size,
+  name = 'add',
+  size = 24,
   opticalSize,
   fill = 0,
   color,
@@ -32,6 +32,9 @@ export function Icon({
 }: IconProps) {
   // Inherit tokens from nearest parent Frame via FrameContext.
   const tokens = useTokens();
+  const frameCtx = useFrameContext();
+  const resolvedTheme = frameCtx?.theme ?? 'primary';
+  const resolvedAppearance = frameCtx?.appearance ?? 'main';
 
   // Build the icon's style from the theme tokens and props.
   // Wrapped in useMemo so it only recalculates when the inputs change,
@@ -53,8 +56,8 @@ export function Icon({
     // Use explicit opticalSize if provided, otherwise auto-calculate from fontSize.
     const opsz = opticalSize ?? getOpticalSize(fontSize);
 
-    // Use the provided color, or fall back to the theme's primary text color.
-    const iconColor = color ?? tokens.textPrimary[tokens.gamut];
+    // Use the provided color, or fall back to the inherited theme/appearance text color.
+    const iconColor = color ?? tokens.colors[resolvedTheme][resolvedAppearance].fontPrimary;
 
     // Build the font family name from the theme's icon variant setting.
     // Example: variant 'rounded' → 'Material Symbols Rounded'
@@ -80,7 +83,7 @@ export function Icon({
       fontVariationSettings, // web-only: controls the variable font axes listed above
       ...style,
     } as TextStyle; // Cast needed because web-only properties aren't in RN's type definitions
-  }, [tokens, size, opticalSize, fill, color, style]);
+  }, [tokens, size, opticalSize, fill, color, style, resolvedTheme, resolvedAppearance]);
 
   // Material Symbols renders icons as text ligatures — the icon name (like "home")
   // is passed as text content, and the font renders it as the icon glyph.

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

@@ -23,9 +23,9 @@ export interface IconProps {
    * @example `'home'`, `'settings'`, `'check'`, `'expand_more'`, `'delete'`, `'add'`, `'search'`
    * @see {@link https://fonts.google.com/icons Browse all icons}
    */
-  readonly name: string;
+  readonly name?: string;
 
-  /** Font size in pixels. @default tokens.typography.fontSizes['05'] (16px) */
+  /** Font size in pixels. @default 24 */
   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

@@ -1,7 +1,8 @@
 import React, { useContext, useMemo } from 'react';
 import { Text as RNText } from 'react-native';
 import type { TextStyle } from 'react-native';
-import { useTokens } from 'newtone-api';
+import { useTokens, useFrameContext } from 'newtone-api';
+import type { ThemeName, AppearanceName } from 'newtone-api';
 import { TextScopeContext, resolveTextColor } from './Text';
 import type { TextSpanProps, TextWeight } from './Text.types';
 
@@ -11,18 +12,21 @@ import type { TextSpanProps, TextWeight } from './Text.types';
  * 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 tokens = useTokens();
   const scopeCtx = useContext(TextScopeContext);
+  const frameCtx = useFrameContext();
+  const resolvedTheme: ThemeName = frameCtx?.theme ?? 'primary';
+  const resolvedAppearance: AppearanceName = frameCtx?.appearance ?? 'main';
 
   const spanStyle = useMemo<TextStyle>(() => {
     const s: TextStyle = {};
-    if (color) s.color = resolveTextColor(color, tokens);
+    if (color) s.color = resolveTextColor(color, tokens, resolvedTheme, resolvedAppearance);
     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);
+    if (highlight) s.backgroundColor = resolveTextColor(highlight, tokens, resolvedTheme, resolvedAppearance);
     return s;
-  }, [tokens, scopeCtx, color, weight, italic, underline, highlight]);
+  }, [tokens, scopeCtx, color, weight, italic, underline, highlight, resolvedTheme, resolvedAppearance]);
 
   return React.createElement(
     RNText,

package/src/primitives/Text/Text.tsx

@@ -4,8 +4,10 @@ import type { LayoutChangeEvent, TextStyle } from 'react-native';
 import { resolveResponsiveSize, estimateLineWidths, BREAKPOINT_ROLE_SCALE, scaleRoleStep, REFERENCE_LINE_HEIGHT_RATIO, buildFontFeatureSettings, SEMANTIC_WEIGHT_MAP, ROLE_DEFAULT_WEIGHTS } from '@newtonedev/fonts';
 import { useTokens } from 'newtone-api';
 import { useNewtoneTheme } from 'newtone-api';
+import { useFrameContext } from 'newtone-api';
 import type { UseTokensResult } from 'newtone-api';
-import type { TextProps, TextColor } from './Text.types';
+import type { ThemeName, AppearanceName } from 'newtone-api';
+import type { TextProps, TextColor, TextRole } from './Text.types';
 import { useLocalCalibration } from 'newtone-api';
 import { useTypographyCalibrations } from 'newtone-api';
 import { enqueueObservation } from 'newtone-api';
@@ -21,21 +23,27 @@ export const TextScopeContext = createContext<{
   readonly weights: { readonly regular: number; readonly medium: number; readonly bold: number };
 } | null>(null);
 
+/** Roles considered "large text" — accent uses accentLarge (lighter). */
+const LARGE_TEXT_ROLES = new Set<TextRole>(['headline', 'title', 'heading', 'subheading']);
+
 /**
  * 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.
+ * Neutral colors use the inherited theme/appearance from the nearest Frame.
+ * Accent uses accentLarge (large text) or accentSmall (small text) from the inherited theme/appearance.
  */
-export function resolveTextColor(color: TextColor, tokens: UseTokensResult): string {
-  const { gamut } = tokens;
+export function resolveTextColor(
+  color: TextColor,
+  tokens: UseTokensResult,
+  theme: ThemeName = 'primary',
+  appearance: AppearanceName = 'main',
+  role: TextRole = 'body',
+): string {
   switch (color) {
-    case 'primary': return tokens.textPrimary[gamut];
-    case 'secondary': return tokens.textSecondary[gamut];
-    case 'tertiary': return tokens.textTertiary[gamut];
-    case 'disabled': return tokens.textDisabled[gamut];
-    case 'accent': return tokens.accent.fill[gamut];
-    case 'success': return tokens.success.fill[gamut];
-    case 'warning': return tokens.warning.fill[gamut];
-    case 'error': return tokens.error.fill[gamut];
+    case 'primary': return tokens.colors[theme][appearance].fontPrimary;
+    case 'secondary': return tokens.colors[theme][appearance].fontSecondary;
+    case 'tertiary': return tokens.colors[theme][appearance].fontTertiary;
+    case 'disabled': return tokens.colors[theme][appearance].fontDisabled;
+    case 'accent': return tokens.colors[theme][appearance][LARGE_TEXT_ROLES.has(role) ? 'accentLarge' : 'accentSmall'];
   }
 }
 
@@ -90,7 +98,7 @@ function TextBase({
   weight: weightOverride,
   align,
   numberOfLines,
-  elevation = 1,
+  elevation,
   style,
   accessibilityRole: accessibilityRoleOverride,
   testID,
@@ -102,6 +110,9 @@ function TextBase({
 }: TextProps) {
   const tokens = useTokens(elevation);
   const { config, reportingEndpoint } = useNewtoneTheme();
+  const frameCtx = useFrameContext();
+  const resolvedTheme: ThemeName = frameCtx?.theme ?? 'primary';
+  const resolvedAppearance: AppearanceName = frameCtx?.appearance ?? 'main';
 
   const size = sizeOverride ?? 'md';
   const fontSlot = tokens.typography.fonts[scope];
@@ -195,13 +206,13 @@ function TextBase({
       fontFamily: fontSlot.family,
       fontSize: activeStep.fontSize,
       fontWeight: String(resolvedFontWeight) as TextStyle['fontWeight'],
-      color: resolveTextColor(color, tokens),
+      color: resolveTextColor(color, tokens, resolvedTheme, resolvedAppearance, role),
       lineHeight: correctedLineHeight,
       textAlign: align,
       ...(vcOffset !== 0 ? { transform: [{ translateY: vcOffset }] } : {}),
       ...(featureSettings ? { fontFeatureSettings: featureSettings } as any : {}),
     };
-  }, [tokens, fontSlot, step, resolvedStep, responsive, isAdaptive, resolvedFontWeight, color, align, config.typography.fontMetrics, centerVertically, features]);
+  }, [tokens, fontSlot, step, resolvedStep, responsive, isAdaptive, resolvedFontWeight, color, align, config.typography.fontMetrics, centerVertically, features, resolvedTheme, resolvedAppearance]);
 
   // 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.

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

@@ -8,7 +8,7 @@ export type TextSize = 'sm' | 'md' | 'lg';
 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';
+export type TextColor = 'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent';
 
 /** Font scope — selects which font family slot to use. @default 'main' */
 export type TextScope = 'main' | 'display' | 'mono' | 'currency';
@@ -66,10 +66,7 @@ export interface TextProps {
    * - `'secondary'` — Subdued/muted text (captions, labels)
    * - `'tertiary'` — Hints, placeholders
    * - `'disabled'` — Disabled text elements
-   * - `'accent'` — Accent palette color for links/actions
-   * - `'success'` — Success palette color for positive indicators
-   * - `'warning'` — Warning palette color for caution indicators
-   * - `'error'` — Error palette color for destructive/error indicators
+   * - `'accent'` — Accent color from the inherited theme/appearance (accentLarge for large text, accentSmall for small text)
    *
    * @default 'primary'
    */
@@ -89,7 +86,7 @@ export interface TextProps {
   /** Maximum number of lines before truncation with ellipsis. When omitted, text wraps freely. */
   readonly numberOfLines?: number;
 
-  /** Elevation level for token computation. @default 1 */
+  /** Elevation level for token computation. When omitted, inherits from nearest parent Frame. */
   readonly elevation?: ElevationLevel;
 
   /** Style overrides (applied last). Supports a single style or an array of styles. */

package/src/primitives/Wrapper/Wrapper.styles.ts

@@ -8,6 +8,9 @@ import type {
   PaddingProp,
   GapProp,
   SizingMode,
+  PositionType,
+  OffsetValue,
+  OverflowMode,
 } from '../Frame/Frame.types';
 import {
   resolvePadding,
@@ -33,6 +36,16 @@ export interface WrapperStyleInput {
   readonly maxWidth?: number;
   readonly minHeight?: number;
   readonly maxHeight?: number;
+
+  // Positioning
+  readonly position?: PositionType;
+  readonly top?: OffsetValue;
+  readonly right?: OffsetValue;
+  readonly bottom?: OffsetValue;
+  readonly left?: OffsetValue;
+  readonly zIndex?: number;
+  readonly overflow?: OverflowMode;
+  readonly opacity?: number;
 }
 
 /**
@@ -58,6 +71,14 @@ export function getWrapperStyles(input: WrapperStyleInput): ViewStyle {
     maxWidth,
     minHeight,
     maxHeight,
+    position,
+    top,
+    right,
+    bottom,
+    left,
+    zIndex,
+    overflow,
+    opacity,
   } = input;
 
   // We build styles as a plain object first, then validate it through
@@ -107,6 +128,17 @@ export function getWrapperStyles(input: WrapperStyleInput): ViewStyle {
   if (minHeight !== undefined) container.minHeight = minHeight;
   if (maxHeight !== undefined) container.maxHeight = maxHeight;
 
+  // ── Positioning ──
+  // Set CSS position mode and offsets for absolute/fixed/sticky positioning.
+  if (position) container.position = position;
+  if (top !== undefined) container.top = top;
+  if (right !== undefined) container.right = right;
+  if (bottom !== undefined) container.bottom = bottom;
+  if (left !== undefined) container.left = left;
+  if (zIndex !== undefined) container.zIndex = zIndex;
+  if (overflow) container.overflow = overflow;
+  if (opacity !== undefined) container.opacity = opacity;
+
   // Pass through StyleSheet.create() to validate and optimize the styles,
   // then extract the single style object with `.c`.
   return StyleSheet.create({ c: container as ViewStyle }).c;

package/src/primitives/Wrapper/Wrapper.tsx

@@ -44,6 +44,16 @@ export function Wrapper({
   maxWidth,
   minHeight,
   maxHeight,
+  // Positioning
+  position,
+  top,
+  right,
+  bottom,
+  left,
+  zIndex,
+  overflow,
+  pointerEvents,
+  opacity,
   style,
   // Testing & platform
   testID,
@@ -51,9 +61,8 @@ export function Wrapper({
   ref,
 }: WrapperProps) {
   // Get the theme's design tokens so we can convert spacing names (like 'md')
-  // into pixel values. The "1" is the default elevation level — Wrapper doesn't
-  // have its own elevation, but tokens need one for the spacing lookups.
-  const tokens = useTokens(1);
+  // into pixel values. Wrapper inherits elevation from FrameContext automatically.
+  const tokens = useTokens();
 
   // Calculate the layout styles (direction, spacing, alignment, sizing).
   // Wrapped in useMemo so it only recalculates when one of the props changes,
@@ -74,11 +83,20 @@ export function Wrapper({
       maxWidth,
       minHeight,
       maxHeight,
+      position,
+      top,
+      right,
+      bottom,
+      left,
+      zIndex,
+      overflow,
+      opacity,
     }),
     [
       tokens, direction, wrap, reverse,
       align, justify, padding, gap,
       width, height, minWidth, maxWidth, minHeight, maxHeight,
+      position, top, right, bottom, left, zIndex, overflow, opacity,
     ],
   );
 
@@ -93,6 +111,7 @@ export function Wrapper({
       ref={ref}
       testID={testID}
       nativeID={nativeID}
+      pointerEvents={pointerEvents}
       // Wrapper is a layout-only container with no semantic meaning.
       // "none" tells screen readers to skip this element and read its children directly.
       accessibilityRole="none"

package/src/primitives/Wrapper/Wrapper.types.ts

@@ -6,6 +6,10 @@ import type {
   PaddingProp,
   GapProp,
   SizingMode,
+  PositionType,
+  OffsetValue,
+  OverflowMode,
+  PointerEventsMode,
 } from '../Frame/Frame.types';
 
 /**
@@ -131,6 +135,47 @@ export interface WrapperProps {
   /** Maximum height in pixels. */
   readonly maxHeight?: number;
 
+  // ── Positioning ──
+
+  /**
+   * CSS position mode.
+   *
+   * `'fixed'` and `'sticky'` are web-only (supported via react-native-web).
+   * React Native natively supports `'absolute'` and `'relative'`.
+   */
+  readonly position?: PositionType;
+
+  /** Offset from the top edge. Accepts pixels (number) or percentage string. */
+  readonly top?: OffsetValue;
+
+  /** Offset from the right edge. Accepts pixels (number) or percentage string. */
+  readonly right?: OffsetValue;
+
+  /** Offset from the bottom edge. Accepts pixels (number) or percentage string. */
+  readonly bottom?: OffsetValue;
+
+  /** Offset from the left edge. Accepts pixels (number) or percentage string. */
+  readonly left?: OffsetValue;
+
+  /** Stacking order. Higher values render above lower values. */
+  readonly zIndex?: number;
+
+  /** Content overflow behavior. */
+  readonly overflow?: OverflowMode;
+
+  /**
+   * Controls whether the element can be the target of touch/pointer events.
+   *
+   * - `'auto'` — default, element and children receive events
+   * - `'none'` — element and children are invisible to events (pass through)
+   * - `'box-none'` — element ignores events but children can receive them
+   * - `'box-only'` — element receives events but children cannot
+   */
+  readonly pointerEvents?: PointerEventsMode;
+
+  /** Opacity of the element (0 = fully transparent, 1 = fully opaque). */
+  readonly opacity?: number;
+
   // ── Testing & Platform ──
 
   /** Test identifier — maps to `data-testid` on web. Used by testing libraries. */