@newtonedev/components 0.1.13 → 0.1.14

package/src/index.ts

@@ -2,6 +2,7 @@
 export {
   NewtoneProvider,
   useNewtoneTheme,
+  useScheme,
   FrameContext,
   useFrameContext,
   useBreakpoint,
@@ -11,18 +12,21 @@ export {
   DEFAULT_ROLE_SCALES,
   useTokens,
   computeTokens,
-  NEUTRAL_DEFAULTS,
-  ACCENT_DEFAULTS,
+  computeSwatches,
+  computeColors,
+  resolveTheme,
+  PRIMARY_DEFAULTS,
+  SECONDARY_DEFAULTS,
+  TERTIARY_DEFAULTS,
   SUCCESS_DEFAULTS,
   WARNING_DEFAULTS,
   ERROR_DEFAULTS,
+  DEFAULT_THEME_MAPPINGS,
   buildGoogleFontsUrl,
   measureAvgCharWidth,
   useLocalCalibration,
   useTypographyCalibrations,
   enqueueObservation,
-  migrateV1ToV2,
-  isV2TokenOverrides,
 } from 'newtone-api';
 export type {
   ColorMode,
@@ -36,11 +40,16 @@ export type {
   FontConfig,
   FontWeights,
   FontSlot,
-  TokenOverrides,
   TokenColor,
-  PaletteModeTokens,
-  PaletteTokenOverrides,
-  LegacyTokenOverrides,
+  TokenName,
+  ContrastLevel,
+  PaletteId,
+  ThemeName,
+  AppearanceName,
+  ColorRef,
+  AppearanceMapping,
+  ThemeMapping,
+  ThemeMappings,
   FontSizeScale,
   LineHeightScale,
   RoleSizeStep,
@@ -53,8 +62,17 @@ export type {
   FrameContextValue,
   UseTokensResult,
   PaletteDefaults,
+  ContrastLevelDefaults,
+  SwatchDefaults,
   ResolvedTokens,
-  PaletteTokens,
+  ResolvedSwatches,
+  PaletteColors,
+  ContrastLevelColors,
+  ElevationColors,
+  ElevationName,
+  AppearanceTokens,
+  ThemeTokens,
+  ResolvedColor,
   DynamicRange,
   ColorResult,
   Srgb,
@@ -113,6 +131,15 @@ export type { ButtonProps, ButtonVariant, ButtonSemantic, ButtonSize, ButtonIcon
 export { Card } from './composites/layout/Card/Card';
 export type { CardProps } from './composites/layout/Card/Card.types';
 
+export { Chip } from './composites/display/Chip/Chip';
+export type { ChipProps, ChipVariant, ChipSemantic, ChipSize } from './composites/display/Chip/Chip.types';
+
+export { Divider } from './composites/layout/Divider/Divider';
+export type { DividerProps, DividerOrientation } from './composites/layout/Divider/Divider.types';
+
+export { ContentCard } from './composites/layout/ContentCard/ContentCard';
+export type { ContentCardProps, ContentCardVariant } from './composites/layout/ContentCard/ContentCard.types';
+
 export { TextInput } from './composites/form-controls/TextInput/TextInput';
 export type { TextInputProps } from './composites/form-controls/TextInput/TextInput.types';
 
@@ -145,6 +172,13 @@ export type { SidebarProps } from './composites/layout/Sidebar/Sidebar.types';
 export { Navbar } from './composites/layout/Navbar/Navbar';
 export type { NavbarProps } from './composites/layout/Navbar/Navbar.types';
 
+// Branding
+export { LogoMonogram } from './composites/branding/LogoMonogram/LogoMonogram';
+export type { LogoMonogramProps } from './composites/branding/LogoMonogram/LogoMonogram.types';
+
+export { LogoWordmark } from './composites/branding/LogoWordmark/LogoWordmark';
+export type { LogoWordmarkProps } from './composites/branding/LogoWordmark/LogoWordmark.types';
+
 // Component registry + code generation
 export type {
   CategoryMeta,

package/src/primitives/Frame/Frame.styles.ts

@@ -1,7 +1,7 @@
 import type { ViewStyle } from 'react-native';
 import { StyleSheet } from 'react-native';
-import type { ResolvedTokens, ColorGamut } from 'newtone-api';
-import type { FrameElevation } from 'newtone-api';
+import type { ResolvedTokens, AppearanceTokens } from 'newtone-api';
+import type { FrameElevation, ThemeName, AppearanceName } from 'newtone-api';
 import type {
   PaddingProp,
   GapProp,
@@ -11,6 +11,9 @@ import type {
   Justification,
   RadiusProp,
   LayoutMode,
+  PositionType,
+  OffsetValue,
+  OverflowMode,
 } from './Frame.types';
 import {
   resolvePadding,
@@ -27,9 +30,12 @@ import {
 
 export interface FrameStyleInput {
   readonly tokens: ResolvedTokens;
-  readonly gamut: ColorGamut;
   readonly frameElevation: FrameElevation;
 
+  // Theme / Appearance
+  readonly theme?: ThemeName;
+  readonly appearance?: AppearanceName;
+
   // Layout
   readonly layout?: LayoutMode;
   readonly direction?: Direction;
@@ -54,6 +60,16 @@ export interface FrameStyleInput {
   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;
+
   // Appearance
   readonly radius?: RadiusProp;
   readonly bordered?: boolean;
@@ -87,8 +103,9 @@ export interface FrameStyles {
 export function getFrameStyles(input: FrameStyleInput): FrameStyles {
   const {
     tokens,
-    gamut,
     frameElevation,
+    theme = 'primary',
+    appearance = 'main',
     layout = 'flex',
     direction = 'vertical',
     wrap = false,
@@ -105,6 +122,14 @@ export function getFrameStyles(input: FrameStyleInput): FrameStyles {
     maxWidth,
     minHeight,
     maxHeight,
+    position,
+    top,
+    right,
+    bottom,
+    left,
+    zIndex,
+    overflow,
+    opacity,
     radius,
     bordered = false,
     disabled = false,
@@ -116,9 +141,12 @@ export function getFrameStyles(input: FrameStyleInput): FrameStyles {
   const container: Record<string, unknown> = {};
 
   // ── Background & foreground ──
-  // Set the surface color and default text color from the current theme.
-  container.backgroundColor = tokens.background[gamut];
-  container.color = tokens.textPrimary[gamut];
+  // Resolve the appearance tokens for the selected theme + appearance.
+  const appearanceTokens: AppearanceTokens = tokens.colors[theme][appearance];
+
+  // Set the surface color and default text color from the resolved appearance.
+  container.backgroundColor = appearanceTokens.background;
+  container.color = appearanceTokens.fontPrimary;
 
   // ── Layout mode ──
   if (layout === 'flex') {
@@ -172,6 +200,15 @@ export function getFrameStyles(input: FrameStyleInput): FrameStyles {
   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;
+
   // ── Radius ──
   // Round the corners of the Frame (e.g. for cards, buttons, pills).
   if (radius !== undefined) {
@@ -188,11 +225,15 @@ export function getFrameStyles(input: FrameStyleInput): FrameStyles {
     }
   }
 
+  // ── Overflow ──
+  // Explicit overflow prop overrides the auto-overflow from radius.
+  if (overflow) container.overflow = overflow;
+
   // ── Border ──
   // Add a thin border using the theme's border color.
   if (bordered) {
     container.borderWidth = 1;
-    container.borderColor = tokens.border[gamut];
+    container.borderColor = appearanceTokens.fontTertiary;
   }
 
   // ── Outer shadow (elevation 2) ──
@@ -207,9 +248,11 @@ export function getFrameStyles(input: FrameStyleInput): FrameStyles {
     container.elevation = 4; // Android-specific shadow depth
   }
 
-  // ── Disabled ──
-  // Make the Frame look faded when disabled.
-  if (disabled) {
+  // ── Opacity ──
+  // Explicit opacity takes precedence over the disabled fade.
+  if (opacity !== undefined) {
+    container.opacity = opacity;
+  } else if (disabled) {
     container.opacity = 0.5;
   }
 
@@ -217,7 +260,7 @@ export function getFrameStyles(input: FrameStyleInput): FrameStyles {
   // When the user is pressing an interactive Frame, shift the background
   // to a darker "sunken" shade to give visual feedback.
   const pressed = StyleSheet.create({
-    s: { backgroundColor: tokens.backgroundSunken[gamut] },
+    s: { backgroundColor: appearanceTokens.fontSecondary },
   }).s;
 
   // ── Grid web style (web-only) ──

package/src/primitives/Frame/Frame.tsx

@@ -2,19 +2,15 @@ import React, { useMemo } from 'react';
 import { View, Pressable, Text } from 'react-native';
 import type { ViewStyle, TextStyle } from 'react-native';
 import type { FrameProps } from './Frame.types';
-import type { ElevationLevel, FrameElevation } from 'newtone-api';
+import type { ElevationLevel, FrameElevation, ElevationName, ThemeName, AppearanceName } from 'newtone-api';
 import { FrameContext, useFrameContext } from 'newtone-api';
-import { useNewtoneTheme } from 'newtone-api';
+import { useNewtoneTheme, _ThemeContext } from 'newtone-api';
 import { computeTokens } from 'newtone-api';
 import { getFrameStyles } from './Frame.styles';
 import { useFocusVisible } from '../useFocusVisible';
 
 /**
  * Wrap raw string/number children in <Text> so they display correctly.
- *
- * In React Native, raw text like <View>"hello"</View> will crash on native
- * and show console warnings on web. All text must be inside a <Text> element.
- * This helper scans children and auto-wraps any bare strings or numbers.
  */
 function wrapTextChildren(
   children: React.ReactNode,
@@ -28,16 +24,15 @@ function wrapTextChildren(
   });
 }
 
+/** Map numeric elevation levels to named elevations for the swatches layer. */
+const ELEVATION_MAP: Record<ElevationLevel, ElevationName> = {
+  0: 'sunken',
+  1: 'grounded',
+  2: 'elevated',
+};
+
 /**
  * Convert user-facing FrameElevation (-2..2) to internal ElevationLevel (0..2).
- *
- * | Frame | Internal | Background |
- * |:-----:|:--------:|:-----------|
- * |  -2   |    0     | Sunken     |
- * |  -1   |    0     | Sunken     |
- * |   0   |    1     | Default    |
- * |   1   |    2     | Elevated   |
- * |   2   |    2     | Elevated   |
  */
 function toElevationLevel(frameElevation: FrameElevation): ElevationLevel {
   if (frameElevation <= -1) return 0;
@@ -53,45 +48,16 @@ function toElevationLevel(frameElevation: FrameElevation): ElevationLevel {
  * and interactivity capabilities.
  *
  * Frames can be nested. Inner frames override outer frames for their subtree.
- * Unspecified props inherit from the nearest parent Frame.
- *
- * @example
- * ```tsx
- * // Basic layout
- * <Frame direction="horizontal" gap="md" padding="lg" align="center">
- *   <Button onPress={() => {}}>Save</Button>
- *   <Button variant="tertiary" onPress={() => {}}>Cancel</Button>
- * </Frame>
- * ```
- *
- * @example
- * ```tsx
- * // Card-like frame
- * <Frame
- *   elevation={2}
- *   radius="lg"
- *   padding="xl"
- *   bordered
- *   onPress={() => navigate('/details')}
- * >
- *   <Text>Clickable card</Text>
- * </Frame>
- * ```
- *
- * @example
- * ```tsx
- * // Grid layout (web)
- * <Frame layout="grid" columns={3} gap="md" padding="lg">
- *   <Frame radius="md" padding="md" bordered>Cell 1</Frame>
- *   <Frame radius="md" padding="md" bordered>Cell 2</Frame>
- *   <Frame radius="md" padding="md" bordered>Cell 3</Frame>
- * </Frame>
- * ```
  */
 export function Frame({
   children,
   // Elevation
   elevation,
+  // Scheme
+  scheme,
+  // Theme / Appearance
+  theme,
+  appearance,
   // Layout
   layout,
   direction,
@@ -112,6 +78,16 @@ export function Frame({
   maxWidth,
   minHeight,
   maxHeight,
+  // Positioning
+  position,
+  top,
+  right,
+  bottom,
+  left,
+  zIndex,
+  overflow,
+  pointerEvents,
+  opacity,
   // Appearance
   radius,
   bordered,
@@ -129,45 +105,54 @@ export function Frame({
   // Style override
   style,
 }: FrameProps) {
-  // Read the global theme configuration and current color mode (light/dark).
-  const { config, mode, gamut } = useNewtoneTheme();
-  // Read the elevation from the nearest parent Frame (if nested).
+  const themeCtx = useNewtoneTheme();
+  const { mode, gamut } = themeCtx;
   const parentFrameCtx = useFrameContext();
 
-  // The user-facing elevation (-2 to 2) controls visual depth (shadows, background).
+  // Resolve which config to use: explicit scheme > inherited from parent > default.
+  const resolvedConfig = useMemo(() => {
+    if (scheme && themeCtx.schemes) {
+      const schemeConfig = themeCtx.schemes[scheme];
+      if (schemeConfig) return schemeConfig;
+    }
+    return themeCtx.config;
+  }, [scheme, themeCtx.schemes, themeCtx.config]);
+
+  // Track whether this Frame switches the scheme (needs theme context override).
+  const isSchemeOverride = resolvedConfig !== themeCtx.config;
+
+  // Resolve theme/appearance: explicit prop > parent Frame > defaults.
+  const resolvedTheme: ThemeName = theme ?? parentFrameCtx?.theme ?? 'primary';
+  const resolvedAppearance: AppearanceName = appearance ?? parentFrameCtx?.appearance ?? 'main';
+
   const resolvedFrameElevation: FrameElevation = elevation ?? 0;
 
-  // Convert user-facing elevation to internal level (0-2) for token computation.
-  // When no elevation is set, inherit from parent Frame or default to 1.
   const resolvedElevation: ElevationLevel = elevation !== undefined
     ? toElevationLevel(elevation)
     : parentFrameCtx?.elevation ?? 1;
 
-  // Generate the design tokens (colors, spacing, fonts) for this Frame.
-  // Frame computes its own tokens instead of using useTokens() because
-  // useTokens() reads from FrameContext — but this Frame IS the provider,
-  // so it needs to compute fresh tokens from the resolved theme/elevation.
-  // Wrapped in useMemo so it only recalculates when the theme/mode/elevation changes.
+  // Compute tokens with gamut pre-applied (no [gamut] indexing needed downstream).
   const tokens = useMemo(() => {
     return computeTokens(
-      config.colorSystem,
+      resolvedConfig.colorSystem,
       mode,
-      resolvedElevation,
-      config.spacing,
-      config.radius,
-      config.typography,
-      config.icons,
-      config.tokenOverrides,
+      gamut,
+      ELEVATION_MAP[resolvedElevation],
+      resolvedConfig.spacing,
+      resolvedConfig.radius,
+      resolvedConfig.typography,
+      resolvedConfig.icons,
+      resolvedConfig.themeMappings,
+      resolvedConfig.swatchDefaults,
     );
-  }, [config, mode, resolvedElevation]);
+  }, [resolvedConfig, mode, gamut, resolvedElevation]);
 
-  // Calculate all visual styles (background, layout, border, shadow, etc.).
-  // Only recalculates when one of the style-related props changes.
   const styles = useMemo(
     () => getFrameStyles({
       tokens,
-      gamut,
       frameElevation: resolvedFrameElevation,
+      theme: resolvedTheme,
+      appearance: resolvedAppearance,
       layout,
       direction,
       wrap,
@@ -184,29 +169,53 @@ export function Frame({
       maxWidth,
       minHeight,
       maxHeight,
+      position,
+      top,
+      right,
+      bottom,
+      left,
+      zIndex,
+      overflow,
+      opacity,
       radius,
       bordered,
       disabled,
     }),
     [
-      tokens, gamut, resolvedFrameElevation,
+      tokens, resolvedFrameElevation, resolvedTheme, resolvedAppearance,
       layout, direction, wrap, reverse, columns, rows,
       align, justify, padding, gap,
       width, height, minWidth, maxWidth, minHeight, maxHeight,
+      position, top, right, bottom, left, zIndex, overflow, opacity,
       radius, bordered, disabled,
     ],
   );
 
-  // This is the value that child components will inherit via FrameContext.
-  // Any nested Frame, Text, Icon, etc. will read this theme and elevation.
+  // Resolved scheme name: explicit prop > inherited from parent Frame.
+  const resolvedScheme = scheme ?? parentFrameCtx?.scheme;
+
   const contextValue = useMemo(
-    () => ({ elevation: resolvedElevation, tokens }),
-    [resolvedElevation, tokens],
+    () => ({
+      elevation: resolvedElevation,
+      tokens,
+      scheme: resolvedScheme,
+      theme: resolvedTheme,
+      appearance: resolvedAppearance,
+    }),
+    [resolvedElevation, tokens, resolvedScheme, resolvedTheme, resolvedAppearance],
   );
 
-  // Some styles only work on web browsers (CSS grid, inset shadows).
-  // We collect them separately and cast them to ViewStyle so React Native
-  // doesn't complain about unknown properties (they're silently ignored on native).
+  // When this Frame switches the scheme, override ThemeContext so that
+  // useNewtoneTheme().config returns the scheme's config for descendants.
+  const schemeThemeCtx = useMemo(() => {
+    if (!isSchemeOverride) return null;
+    return {
+      ...themeCtx,
+      config: resolvedConfig,
+      activeScheme: scheme ?? themeCtx.activeScheme,
+    };
+  }, [isSchemeOverride, themeCtx, resolvedConfig, scheme]);
+
   const webOverrides: ViewStyle[] = [];
   if (styles.gridWebStyle) {
     webOverrides.push(styles.gridWebStyle as unknown as ViewStyle);
@@ -215,94 +224,83 @@ export function Frame({
     webOverrides.push({ boxShadow: styles.insetBoxShadow } as unknown as ViewStyle);
   }
 
-  // Normalize user's custom styles into an array for merging.
   const userStyles = Array.isArray(style) ? style : style ? [style] : [];
 
-  // If the Frame has onPress or href, it needs to respond to taps/clicks.
-  // In that case we render a Pressable (tappable); otherwise a plain View.
+
   const isInteractive = onPress !== undefined || href !== undefined;
 
-  // Detect keyboard-only focus (Tab, arrows) vs mouse/touch focus.
-  // Only shows a visible focus ring when the user navigated via keyboard,
-  // matching the browser's native :focus-visible behavior.
   const { isFocusVisible, focusProps } = useFocusVisible();
 
-  // Focus ring style: 2px solid outline in the theme's interactive color,
-  // offset by 2px so it doesn't overlap the Frame's border.
-  // Uses CSS outline properties — silently ignored on native platforms.
+  // Focus ring: uses the emphasis background of the resolved theme as the outline color.
   const focusRingStyle = isFocusVisible && !disabled ? {
     outlineWidth: 2,
     outlineStyle: 'solid',
-    outlineColor: tokens.accent.fill[gamut],
+    outlineColor: tokens.colors[resolvedTheme].emphasis.background,
     outlineOffset: 2,
-  } as unknown as ViewStyle : undefined; // web-only
+  } as unknown as ViewStyle : undefined;
 
-  // Spread focus event handlers onto the Pressable. These are web-only
-  // handlers supported by react-native-web — silently ignored on native.
-  const webFocusProps = isInteractive ? focusProps as any : {}; // web-only
+  const webFocusProps = isInteractive ? focusProps as any : {};
 
-  // Default text style for any raw strings/numbers passed as children.
-  // Uses the theme's primary text color, default font, and base size.
   const textStyle = useMemo<TextStyle>(
     () => ({
-      color: tokens.textPrimary[gamut],
+      color: tokens.colors[resolvedTheme][resolvedAppearance].fontPrimary,
       fontSize: tokens.typography.fontSizes['05'],
       fontFamily: tokens.typography.fonts.main.family,
       lineHeight: tokens.typography.lineHeights['06'],
     }),
-    [tokens],
+    [tokens, resolvedTheme, resolvedAppearance],
   );
-  // Auto-wrap bare text ("hello") in <Text> elements (required by React Native).
-  // Wrapped in useMemo so it only re-scans children when they or the text style changes.
   const wrappedChildren = useMemo(
     () => wrapTextChildren(children, textStyle),
     [children, textStyle],
   );
 
-  // FrameContext.Provider shares this Frame's theme and elevation with all
-  // descendants, so nested components automatically pick up the right colors.
+  const content = isInteractive ? (
+    <Pressable
+      ref={ref}
+      testID={testID}
+      nativeID={nativeID}
+      pointerEvents={pointerEvents}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityHint={accessibilityHint}
+      accessibilityState={disabled ? { disabled: true } : undefined}
+      onPress={onPress}
+      disabled={disabled}
+      {...(href ? { href, accessibilityRole: 'link' as const } : { accessibilityRole: 'button' as const })}
+      {...webFocusProps}
+      style={({ pressed }) => [
+        styles.container,
+        pressed && !disabled && styles.pressed,
+        focusRingStyle,
+        ...webOverrides,
+        ...userStyles,
+      ]}
+    >
+      {wrappedChildren}
+    </Pressable>
+  ) : (
+    <View
+      ref={ref}
+      testID={testID}
+      nativeID={nativeID}
+      pointerEvents={pointerEvents}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityHint={accessibilityHint}
+      style={[styles.container, ...webOverrides, ...userStyles]}
+    >
+      {wrappedChildren}
+    </View>
+  );
+
+  const wrappedContent = schemeThemeCtx ? (
+    <_ThemeContext.Provider value={schemeThemeCtx}>
+      {content}
+    </_ThemeContext.Provider>
+  ) : content;
+
   return (
     <FrameContext.Provider value={contextValue}>
-      {isInteractive ? (
-        // Pressable handles taps. When href is set, react-native-web renders
-        // it as an <a> tag so it works like a regular link on the web.
-        <Pressable
-          ref={ref}
-          testID={testID}
-          nativeID={nativeID}
-          accessibilityLabel={accessibilityLabel}
-          accessibilityHint={accessibilityHint}
-          // Tell screen readers this is disabled so assistive technology can announce it.
-          accessibilityState={disabled ? { disabled: true } : undefined}
-          onPress={onPress}
-          disabled={disabled}
-          {...(href ? { href, accessibilityRole: 'link' as const } : { accessibilityRole: 'button' as const })}
-          {...webFocusProps}
-          // The style callback receives { pressed: true/false } so we can
-          // change the background when the user is actively pressing.
-          style={({ pressed }) => [
-            styles.container,
-            pressed && !disabled && styles.pressed,
-            focusRingStyle,
-            ...webOverrides,
-            ...userStyles,
-          ]}
-        >
-          {wrappedChildren}
-        </Pressable>
-      ) : (
-        // Non-interactive Frame: just a plain View with no tap handling.
-        <View
-          ref={ref}
-          testID={testID}
-          nativeID={nativeID}
-          accessibilityLabel={accessibilityLabel}
-          accessibilityHint={accessibilityHint}
-          style={[styles.container, ...webOverrides, ...userStyles]}
-        >
-          {wrappedChildren}
-        </View>
-      )}
+      {wrappedContent}
     </FrameContext.Provider>
   );
 }