react-native-terra-ui 0.10.1 → 0.11.0

package/src/components/pressable/variants/PressableScale/index.tsx

@@ -0,0 +1,166 @@
+import { type ComponentRef, forwardRef, useCallback, useEffect, useState } from "react";
+import type {
+  GestureResponderEvent,
+  PressableProps,
+  PressableStateCallbackType,
+  StyleProp,
+  ViewStyle,
+} from "react-native";
+import { Pressable } from "react-native";
+
+import Animated, {
+  Easing,
+  interpolate,
+  useAnimatedStyle,
+  useSharedValue,
+  type WithSpringConfig,
+  type WithTimingConfig,
+  withSpring,
+  withTiming,
+} from "react-native-reanimated";
+import { StyleSheet } from "react-native-unistyles";
+
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
+
+/** A 250ms ease that reads as instant on press-in but never snaps back on release. */
+const DEFAULT_TIMING: WithTimingConfig = {
+  duration: 250,
+  easing: Easing.bezier(0.25, 0.1, 0.25, 1),
+};
+
+export type PressableScaleAnimationConfig =
+  | { type: "timing"; config?: WithTimingConfig }
+  | { type: "spring"; config?: WithSpringConfig };
+
+export interface PressableScaleProps extends Omit<PressableProps, "style" | "disabled"> {
+  /** Scale held at rest. Defaults to `1`. */
+  baseScale?: number;
+  /**
+   * Scale held while pressed. Values below `baseScale` shrink, above it grow.
+   * Defaults to `0.96`.
+   */
+  minScale?: number;
+  /**
+   * Opacity held while pressed, animated on the same curve as the scale.
+   * Defaults to `undefined` — opacity is left untouched so `style` keeps
+   * ownership of it.
+   */
+  pressedOpacity?: number;
+  /**
+   * Drives the press animation. Defaults to `{ type: 'timing' }` with a 250ms
+   * ease; pass `{ type: 'spring' }` for a springy release.
+   */
+  animationConfig?: PressableScaleAnimationConfig;
+  /** Blocks presses and holds the resting scale. Defaults to `false`. */
+  isDisabled?: boolean;
+  /**
+   * Styles for the pressable itself. The function form receives `pressed`
+   * only — `hovered` and `focused` are not tracked, because the animated
+   * style has to be merged outside of `Pressable`'s own callback.
+   */
+  style?: StyleProp<ViewStyle> | ((state: PressableStateCallbackType) => StyleProp<ViewStyle>);
+}
+
+/**
+ * A `Pressable` that animates a scale (and optionally an opacity) between its
+ * resting and pressed states, driven by a single shared `progress` value on the
+ * UI thread.
+ *
+ * Use it anywhere a press deserves physical feedback — cards, list rows, custom
+ * controls. `Button` renders one internally via its `animation` prop.
+ */
+export const PressableScale = forwardRef<ComponentRef<typeof Pressable>, PressableScaleProps>(
+  function PressableScale(
+    {
+      baseScale = 1,
+      minScale = 0.96,
+      pressedOpacity,
+      animationConfig,
+      isDisabled = false,
+      style,
+      onPressIn,
+      onPressOut,
+      ...rest
+    },
+    ref
+  ) {
+    const progress = useSharedValue(0);
+
+    // Only the function form of `style` needs a re-render to resolve; tracking
+    // `pressed` unconditionally would re-render every consumer on every touch.
+    const isStyleFunction = typeof style === "function";
+    const [pressed, setPressed] = useState(false);
+
+    const animateTo = useCallback(
+      (to: number) => {
+        if (animationConfig?.type === "spring") {
+          progress.value = withSpring(to, animationConfig.config);
+          return;
+        }
+        progress.value = withTiming(to, { ...DEFAULT_TIMING, ...animationConfig?.config });
+      },
+      [animationConfig, progress]
+    );
+
+    const handlePressIn = useCallback(
+      (event: GestureResponderEvent) => {
+        animateTo(1);
+        if (isStyleFunction) setPressed(true);
+        onPressIn?.(event);
+      },
+      [animateTo, isStyleFunction, onPressIn]
+    );
+
+    const handlePressOut = useCallback(
+      (event: GestureResponderEvent) => {
+        animateTo(0);
+        if (isStyleFunction) setPressed(false);
+        onPressOut?.(event);
+      },
+      [animateTo, isStyleFunction, onPressOut]
+    );
+
+    // A press that disables its own pressable — `onPress` flipping a button into
+    // a loading state — never gets an `onPressOut`, so release it here instead
+    // of leaving it stuck at the pressed scale.
+    useEffect(() => {
+      if (!isDisabled) return;
+      animateTo(0);
+      setPressed(false);
+    }, [isDisabled, animateTo]);
+
+    const animatedStyle = useAnimatedStyle(() => {
+      const scale = interpolate(progress.value, [0, 1], [baseScale, minScale]);
+      if (pressedOpacity === undefined) {
+        return { transform: [{ scale }] };
+      }
+      return {
+        transform: [{ scale }],
+        opacity: interpolate(progress.value, [0, 1], [1, pressedOpacity]),
+      };
+    });
+
+    const pressableState: PressableStateCallbackType = { pressed };
+
+    return (
+      <AnimatedPressable
+        ref={ref}
+        disabled={isDisabled}
+        {...rest}
+        onPressIn={handlePressIn}
+        onPressOut={handlePressOut}
+        // The animated style goes first so anything the caller sets — a disabled
+        // opacity, say — still wins.
+        style={[styles.root, animatedStyle, isStyleFunction ? style(pressableState) : style]}
+      />
+    );
+  }
+);
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+//
+// PressableScale has no style of its own — this stylesheet exists so the
+// Unistyles Babel plugin swaps the `Pressable` imported above for its
+// Unistyles-aware counterpart. Without it a themed style handed in through
+// `style` freezes at whichever theme was active when it was created.
+const styles = StyleSheet.create(() => ({ root: {} }));

package/src/context/ThemeProvider.tsx

@@ -5,9 +5,9 @@ import { useUnistyles } from "react-native-unistyles";
 
 import { bootstrapTerraUI } from "../theme/registry";
 import {
-  applyAccent,
   applyScheme,
   getThemeSelection,
+  setTheme,
   setThemeMode,
   subscribeThemeSelection,
 } from "../theme/runtime";
@@ -41,13 +41,13 @@ export interface UseThemeResult {
   scheme: Scheme;
   /** Pin a scheme (stops following the system). Same as `setMode(scheme)`. */
   setScheme: (scheme: Scheme) => void;
-  /** Applied accent name, or `undefined` for the base themes. */
-  accent: string | undefined;
+  /** Applied theme name, or `undefined` for the base themes. */
+  themeName: string | undefined;
   /**
-   * Apply a registered accent; `null` restores the base themes. An unknown
-   * name warns in development and leaves the accent unchanged.
+   * Apply a registered theme; `null` restores the base themes. An unknown
+   * name warns in development and leaves the theme unchanged.
    */
-  setAccent: (name: string | null) => void;
+  setTheme: (name: string | null) => void;
   /**
    * How the active scheme is chosen: `system` follows the OS appearance,
    * `light` / `dark` pin a scheme. A system appearance change updates
@@ -59,8 +59,8 @@ export interface UseThemeResult {
 }
 
 /**
- * Access the active theme and switch scheme / mode / accent. Selection state
- * comes from the runtime store, so changes made imperatively (`applyAccent`,
+ * Access the active theme and switch scheme / mode / theme. Selection state
+ * comes from the runtime store, so changes made imperatively (`setTheme`,
  * `setThemeMode`) and through this hook are observed by every consumer.
  */
 export function useTheme(): UseThemeResult {
@@ -71,8 +71,8 @@ export function useTheme(): UseThemeResult {
     theme,
     scheme: (rt.themeName ?? "light") as Scheme,
     setScheme: applyScheme,
-    accent: selection.accent,
-    setAccent: applyAccent,
+    themeName: selection.themeName,
+    setTheme,
     mode: selection.mode,
     setMode: setThemeMode,
   };

package/src/theme/define-config.ts

@@ -1,7 +1,7 @@
 import type { TerraConfig } from "./types";
 
-/** The literal accent names declared in `T.accents`, or `never` when none are declared. */
-type DeclaredAccentNames<T> = T extends { accents: infer A }
+/** The literal theme names declared in `T.themes`, or `never` when none are declared. */
+type DeclaredThemeNames<T> = T extends { themes: infer A }
   ? A extends Record<string, unknown>
     ? keyof A & string
     : never
@@ -9,19 +9,24 @@ type DeclaredAccentNames<T> = T extends { accents: infer A }
 
 /**
  * Identity helper for authoring a {@link TerraConfig} with contextual typing.
- * Has no side effects. With literal `accents`, `defaultAccent` must name one of
- * them; a dynamic `Record<string, Accent>` keeps `defaultAccent` as `string`
+ * Has no side effects. With literal `themes`, `defaultTheme` must name one of
+ * them; a dynamic `Record<string, NamedTheme>` keeps `defaultTheme` as `string`
  * and defers to runtime validation.
  *
  * @example
  * const config = defineTerraConfig({
- *   accents: { indigo: { light: "#4f46e5", dark: "#818cf8" } },
- *   defaultAccent: "indigo",
+ *   themes: { indigo: { light: "#4f46e5", dark: "#818cf8" } },
+ *   defaultTheme: "indigo",
  * });
  * configureTerraUI(config);
  */
 export function defineTerraConfig<const T extends TerraConfig>(
-  config: T & { defaultAccent?: DeclaredAccentNames<T> }
+  config: T & {
+    defaultTheme?: DeclaredThemeNames<T>;
+    schemes?: never;
+    accents?: never;
+    defaultAccent?: never;
+  }
 ): T {
   return config;
 }

package/src/theme/errors.ts

@@ -1,7 +1,7 @@
 /**
  * Thrown for invalid pure configuration input — before any registry, selection,
  * or native state is touched. `path` points at the offending config entry, e.g.
- * `accents.indigo.dark.seed` or `defaultAccent`.
+ * `themes.indigo.dark.seed` or `defaultTheme`.
  */
 export class TerraConfigError extends Error {
   readonly path: string;

package/src/theme/index.ts

@@ -33,23 +33,23 @@ export { defineTerraConfig } from "./define-config";
 export { TerraConfigError } from "./errors";
 export {
   configureTerraUI,
-  getAccentNames,
   getDefaultRadius,
   getIcon,
   getImageComponent,
   getIsConfigured,
   getRequiredIcon,
   getSurfaceElevation,
+  getThemeNames,
   resolveTheme,
 } from "./registry";
 export { createTerraThemes } from "./resolve-config";
 export type { ThemeSelection } from "./runtime";
 export {
-  applyAccent,
   applyScheme,
-  getCurrentAccent,
+  getCurrentTheme,
   getThemeMode,
   getThemeSelection,
+  setTheme,
   setThemeMode,
 } from "./runtime";
 export type { ResolvedScreenMargin } from "./screen-margin";
@@ -60,12 +60,7 @@ export { resolveScreenPadding } from "./screen-padding";
 export { defaultDarkTheme, defaultLightTheme } from "./theme";
 // ─── Types ────────────────────────────────────────────────────────────────────
 export type {
-  Accent,
   AccentColorToken,
-  AccentOverride,
-  AccentSchemeInput,
-  AccentSeed,
-  AccentShorthand,
   ActionColorToken,
   BackgroundColorToken,
   BorderColorToken,
@@ -81,6 +76,7 @@ export type {
   ElevationStyle,
   FontWeightToken,
   LayoutTokens,
+  NamedTheme,
   NeutralColorToken,
   OpacityTokens,
   RadiusComponent,
@@ -110,6 +106,8 @@ export type {
   ThemeColor,
   ThemeMode,
   ThemeRadiusOverride,
+  ThemeSchemeInput,
+  ThemeSeed,
   ThemeSpacingOverride,
   TypeStyle,
   Typography,

package/src/theme/registry.ts

@@ -23,7 +23,6 @@ import type {
   TerraImageComponent,
   TerraSemanticIconName,
   TerraTheme,
-  TerraThemeInput,
   ThemeMode,
 } from "./types";
 import { applyMode, configureUnistyles, hasConfiguredUnistyles, updateThemes } from "./unistyles-adapter";
@@ -81,8 +80,8 @@ let installation: "unconfigured" | "fallback" | "app" = "unconfigured";
 
 export const getIsConfigured = (): boolean => installation !== "unconfigured";
 
-/** Names of the registered accents, in declaration order. Returns a fresh array. */
-export const getAccentNames = (): string[] => [...getInstalledConfig().accentNames];
+/** Names of the registered themes, in declaration order. Returns a fresh array. */
+export const getThemeNames = (): string[] => [...getInstalledConfig().themeNames];
 
 export const getImageComponent = (): TerraImageComponent => settings.imageComponent;
 
@@ -107,22 +106,22 @@ export const getSurfaceElevation = (): ElevationKey => settings.surfaceElevation
 
 /**
  * Resolves one scheme's theme from the installed configuration with the named
- * accent overlaid. Omitting `accentName` selects the base theme (no accent —
- * not the configured `defaultAccent`). An unknown name warns in development
+ * theme selected. Omitting `name` selects the base theme (defaults + shared —
+ * not the configured `defaultTheme`). An unknown name warns in development
  * and falls back to the base theme. Pure with respect to runtime state: it
  * never changes the applied selection.
  */
-export function resolveTheme(scheme: Scheme, accentName?: string): TerraTheme {
+export function resolveTheme(scheme: Scheme, name?: string): TerraTheme {
   const config = getInstalledConfig();
-  let accent: string | null = null;
-  if (accentName !== undefined) {
-    if (config.accentNames.includes(accentName)) {
-      accent = accentName;
+  let themeName: string | null = null;
+  if (name !== undefined) {
+    if (config.themeNames.includes(name)) {
+      themeName = name;
     } else if (__DEV__) {
-      console.warn(`[react-native-terra-ui] Unknown accent "${accentName}"; resolving the base theme.`);
+      console.warn(`[react-native-terra-ui] Unknown theme "${name}"; resolving the base theme.`);
     }
   }
-  return resolveThemeScheme(config, scheme, accent).theme;
+  return resolveThemeScheme(config, scheme, themeName).theme;
 }
 
 // ─── Configuration ───────────────────────────────────────────────────────────
@@ -189,22 +188,15 @@ function deriveMode(config: TerraConfig): ThemeMode {
   return "system";
 }
 
-const pickThemeInput = (config: TerraConfig): TerraThemeInput => ({
-  shared: config.shared,
-  schemes: config.schemes,
-  accents: config.accents,
-  defaultAccent: config.defaultAccent,
-});
-
 function applyConfig(config: TerraConfig, kind: "fallback" | "app"): void {
   // (a) Pure: validate and build everything. Throws leave ALL state untouched.
-  const themeConfig = normalizeThemeInput(pickThemeInput(config));
+  const themeConfig = normalizeThemeInput(config);
   const mode = deriveMode(config);
-  const { themes, diagnostics } = resolveThemes(themeConfig, themeConfig.defaultAccent);
+  const { themes, diagnostics } = resolveThemes(themeConfig, themeConfig.defaultTheme);
   const nextSettings = buildSettings(config);
 
   // (b) Native. `StyleSheet.configure` runs once per app; after that the
-  // rebuilt themes reach the runtime the same way an accent change does, so an
+  // rebuilt themes reach the runtime the same way a theme change does, so an
   // app's config is never stranded behind the fallback's defaults.
   if (hasConfiguredUnistyles()) {
     updateThemes(themes);
@@ -217,7 +209,7 @@ function applyConfig(config: TerraConfig, kind: "fallback" | "app"): void {
   installation = kind;
   settings = nextSettings;
   setInstalledConfig(themeConfig);
-  publishThemeSelection({ accent: themeConfig.defaultAccent ?? undefined, mode });
+  publishThemeSelection({ themeName: themeConfig.defaultTheme ?? undefined, mode });
 
   warnContrastDiagnostics(diagnostics);
 }