@newtonedev/components 0.1.5 → 0.1.7

package/src/tokens/types.ts

@@ -1,9 +1,59 @@
 import type { ColorResult } from 'newtone';
 
+/**
+ * Complete token set for a non-neutral palette (accent, success, warning, error).
+ *
+ * Fill tokens use the palette's key NV position (user-chosen or WCAG auto-derived).
+ * Surface tokens use standard positions from PaletteDefaults, rendered in the palette's hue/saturation.
+ */
+export interface PaletteTokens {
+  // --- Fill: the palette's key color for prominent surfaces ---
+  /** Key color at the palette's keyNormalizedValue (used for primary Button fills, badges, indicators) */
+  readonly fill: ColorResult;
+  /** Key color shifted for hover state */
+  readonly fillHover: ColorResult;
+  /** Key color shifted for pressed/active state */
+  readonly fillActive: ColorResult;
+  /** High-contrast color for text/icons on top of fill (auto: dark text on light fills, light on dark) */
+  readonly onFill: ColorResult;
+
+  // --- Surface: subtle palette-tinted backgrounds ---
+  /** Palette-tinted background at current elevation */
+  readonly background: ColorResult;
+  /** Palette-tinted elevated surface */
+  readonly backgroundElevated: ColorResult;
+  /** Palette-tinted sunken surface */
+  readonly backgroundSunken: ColorResult;
+
+  // --- Interactive surface: interactive elements on palette surfaces ---
+  /** Interactive element background within palette surface */
+  readonly backgroundInteractive: ColorResult;
+  /** Hover state for interactive elements within palette surface */
+  readonly backgroundInteractiveHover: ColorResult;
+  /** Pressed/active state for interactive elements within palette surface */
+  readonly backgroundInteractiveActive: ColorResult;
+
+  // --- Text: palette-hued text on neutral backgrounds ---
+  /** High-contrast palette-colored text */
+  readonly textPrimary: ColorResult;
+  /** Medium-contrast palette-colored text */
+  readonly textSecondary: ColorResult;
+  /** Low-contrast palette-colored text */
+  readonly textTertiary: ColorResult;
+  /** Disabled palette-colored text */
+  readonly textDisabled: ColorResult;
+
+  // --- Border ---
+  /** Palette-colored border */
+  readonly border: ColorResult;
+}
+
 /**
  * Resolved design tokens for a specific mode/theme/elevation combination
  */
 export interface ResolvedTokens {
+  // --- Neutral palette (top-level for convenience — most-used palette) ---
+
   /** Background color for the current surface */
   readonly background: ColorResult;
   /** Background color for elevated surfaces (cards, modals) */
@@ -12,32 +62,40 @@ export interface ResolvedTokens {
   readonly backgroundSunken: ColorResult;
   /**
    * Background color for interactive components with neutral backgrounds.
-   * Uses a fixed -0.035 NV (luminosity) offset from current background to ensure
+   * Uses a fixed NV offset from current background to ensure
    * consistent visual contrast across all elevations (-2 to 2).
    *
-   * Use for: Button (neutral primary), and future components with neutral filled backgrounds.
+   * Use for: Button (neutral primary enabled), and future components with neutral filled backgrounds.
    * Don't use for: Semantic variants (accent/success/error/warning), transparent backgrounds,
    * or primitives (Frame/Wrapper/Text/Icon already handle elevation correctly).
    */
   readonly backgroundInteractive: ColorResult;
-  /** Primary text color (high contrast for body text) */
+  /** Hover state for neutral interactive components (enabled + hoverShift) */
+  readonly backgroundInteractiveHover: ColorResult;
+  /** Pressed/active state for neutral interactive components (enabled + activeShift) */
+  readonly backgroundInteractiveActive: ColorResult;
+  /** Primary text color (high contrast for body text, 4.5:1 default) */
   readonly textPrimary: ColorResult;
-  /** Secondary text color (lower contrast for captions, labels) */
+  /** Secondary text color (lower contrast for captions, labels, 3.0:1 default) */
   readonly textSecondary: ColorResult;
-  /** Interactive element color (buttons, links) */
-  readonly interactive: ColorResult;
-  /** Interactive element hover state */
-  readonly interactiveHover: ColorResult;
-  /** Interactive element active/pressed state */
-  readonly interactiveActive: ColorResult;
+  /** Tertiary text color (hints, placeholders, 2.0:1 default) */
+  readonly textTertiary: ColorResult;
+  /** Disabled text color (disabled elements, 1.5:1 default) */
+  readonly textDisabled: ColorResult;
   /** Border color for subtle separators */
   readonly border: ColorResult;
-  /** Success state color (from success palette, index 2) */
-  readonly success: ColorResult;
-  /** Warning state color (from warning palette, index 3) */
-  readonly warning: ColorResult;
-  /** Error/destructive state color (from error palette, index 4) */
-  readonly error: ColorResult;
+
+  // --- Per-palette token sets ---
+
+  /** Accent palette tokens (palette index 1) — interactive elements, brand color */
+  readonly accent: PaletteTokens;
+  /** Success palette tokens (palette index 2) — positive state indicators */
+  readonly success: PaletteTokens;
+  /** Warning palette tokens (palette index 3) — caution state indicators */
+  readonly warning: PaletteTokens;
+  /** Error palette tokens (palette index 4) — destructive/error state indicators */
+  readonly error: PaletteTokens;
+
   /** Spacing tokens for paddings, gaps, and margins.
    * Token names represent pixel values at Medium (8px) spacing preset.
    * Actual values scale based on the selected spacing preset. */

package/src/tokens/useTokens.ts

@@ -21,59 +21,42 @@ export interface UseTokensResult extends ResolvedTokens {
  * 2. FrameContext values (from nearest parent Frame) are used when elevation is omitted
  * 3. Falls back to NewtoneProvider theme + elevation 1
  *
- * Theme always reads from FrameContext if present, falling back to NewtoneProvider.
+ * When inside a Frame and no explicit elevation override is given, reuses the
+ * Frame's pre-computed tokens to avoid redundant computeTokens calls.
  *
  * @param elevation - Elevation level (0=sunken, 1=default, 2=elevated).
  *                    When omitted, reads from FrameContext or defaults to 1.
  * @returns Resolved design tokens with all necessary colors + resolved elevation
- *
- * @example
- * ```tsx
- * // Inside a <Frame theme="primary" elevation={1}>:
- * function MyComponent() {
- *   const tokens = useTokens(); // Gets primary theme, elevation 2 (mapped from Frame's 1)
- *   return (
- *     <View style={{ backgroundColor: srgbToHex(tokens.background.srgb) }} />
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Elevation-aware component:
- * function ElevationAwareButton() {
- *   const tokens = useTokens();
- *   // Use tokens.elevation to make color decisions
- *   const bg = tokens.elevation === 2 ? tokens.background : tokens.backgroundSunken;
- *   return <View style={{ backgroundColor: srgbToHex(bg.srgb) }} />;
- * }
- * ```
  */
 export function useTokens(elevation?: ElevationLevel): UseTokensResult {
-  const { config, mode, theme: providerTheme } = useNewtoneTheme();
+  const { config, mode } = useNewtoneTheme();
   const frameCtx = useFrameContext();
 
-  // Resolve theme: FrameContext overrides provider
-  const resolvedTheme = frameCtx?.theme ?? providerTheme;
-
   // Resolve elevation: explicit param > FrameContext > default 1
   const resolvedElevation: ElevationLevel = elevation ?? frameCtx?.elevation ?? 1;
 
+  // Optimization: reuse Frame's pre-computed tokens when elevation matches
+  // and no explicit elevation override was given.
+  const canReuse = frameCtx !== null
+    && elevation === undefined
+    && frameCtx.elevation === resolvedElevation;
+
   return useMemo(() => {
-    const themeMapping = config.themes[resolvedTheme];
+    if (canReuse) {
+      return { ...frameCtx!.tokens, elevation: resolvedElevation };
+    }
+
     const tokens = computeTokens(
       config.colorSystem,
       mode,
-      themeMapping,
       resolvedElevation,
-      config.elevation.offsets,
       config.spacing,
       config.radius,
       config.typography,
-      config.icons
+      config.icons,
+      config.tokenOverrides
     );
 
-    // Return tokens + elevation for elevation-aware components
     return { ...tokens, elevation: resolvedElevation };
-  }, [config, mode, resolvedTheme, resolvedElevation]);
+  }, [config, mode, resolvedElevation, canReuse, frameCtx?.tokens]);
 }