@nexub/react-native 0.0.0-stage → 2.1.0

package/lib/typescript/theme/ThemeProvider.d.ts

@@ -0,0 +1,69 @@
+import * as React from 'react';
+import { native, type NativeRoles } from '@nexub/tokens/native';
+import { type ContrastLevel, type Direction, type GlassMode, type NexubMessages, type Product } from '@nexub/core';
+import { type HapticToken } from './haptics.js';
+import type { FontSource } from './fonts.js';
+export type Scheme = 'light' | 'dark';
+export type Roles = {
+    -readonly [K in keyof NativeRoles]: string;
+};
+export type RoleName = keyof Roles;
+export type ElevationLevel = 0 | 1 | 2 | 3;
+export interface NexubTheme {
+    scheme: Scheme;
+    contrast: ContrastLevel;
+    product: Product | undefined;
+    /** Colour roles, already resolved for scheme, contrast, product and seed. */
+    roles: Roles;
+    /** Every native token (spacing, shape, size, type, state, motion). */
+    tokens: typeof native;
+    /** `boxShadow` for an elevation level, undefined for 0. */
+    elevation: (level: ElevationLevel) => string | undefined;
+    /** Effective glass: 'off' when the user has Reduce Transparency on. */
+    glass: GlassMode;
+    reducedMotion: boolean;
+    haptics: boolean;
+    fonts: FontSource;
+    locale: string;
+    dir: Direction;
+    messages: NexubMessages;
+}
+export interface NexubNativeProviderProps {
+    /** @default 'system' */
+    scheme?: Scheme | 'system';
+    /** 'system' = iOS Increase Contrast / Android high-contrast text → 'high'. @default 'system' */
+    contrast?: ContrastLevel | 'system';
+    /** Product brand: remaps the tertiary role family. */
+    product?: Product;
+    /** White-label seed colour (#rgb / #rrggbb); regenerates the `seedTarget` family. */
+    seed?: string;
+    /** @default 'primary' */
+    seedTarget?: 'primary' | 'tertiary';
+    /** Glass intensity (the app persists the user's choice). @default 'balanced' */
+    glass?: GlassMode;
+    /** Haptics on/off (user setting). @default true */
+    haptics?: boolean;
+    /** 'nexub' needs `nexubFonts` loaded; 'system' uses the platform font. @default 'nexub' */
+    fonts?: FontSource;
+    /** BCP 47 locale for Intl formatting. @default 'en' */
+    locale?: string;
+    /** @default derived from `locale` */
+    dir?: Direction;
+    /** Overrides for the default English strings. */
+    messages?: Partial<NexubMessages>;
+    children?: React.ReactNode;
+}
+/**
+ * Theme, accessibility preferences, locale and strings for every
+ * @nexub/react-native component. Wrap the app once, inside the safe-area provider.
+ */
+export declare function NexubNativeProvider({ scheme: schemeProp, contrast: contrastProp, product, seed, seedTarget, glass, haptics, fonts, locale, dir, messages, children, }: NexubNativeProviderProps): React.JSX.Element;
+/** The active theme. Throws outside NexubNativeProvider. */
+export declare function useTheme(): NexubTheme;
+/** Shorthand for `useTheme().roles`. */
+export declare const useRoles: () => Roles;
+/** The active strings: defaults merged with the provider's overrides. */
+export declare const useNexubMessages: () => NexubMessages;
+/** Plays a semantic haptic, unless the user turned haptics off. */
+export declare function useHaptics(): (token: HapticToken) => void;
+//# sourceMappingURL=ThemeProvider.d.ts.map

package/lib/typescript/theme/ThemeProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThemeProvider.d.ts","sourceRoot":"","sources":["../../../src/theme/ThemeProvider.tsx"],"names":[],"mappings":"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"}

package/lib/typescript/theme/fonts.d.ts

@@ -0,0 +1,25 @@
+export declare const nexubFonts: {
+    Inter_400Regular: number;
+    Inter_500Medium: number;
+    Inter_600SemiBold: number;
+    Inter_700Bold: number;
+    PlusJakartaSans_600SemiBold: number;
+    PlusJakartaSans_700Bold: number;
+    PlusJakartaSans_800ExtraBold: number;
+    GeistMono_400Regular: number;
+};
+export type FontFamily = 'sans' | 'display' | 'mono';
+export type FontSource = 'nexub' | 'system';
+/**
+ * Style for a family + weight. With static files the weight lives in the file
+ * name, so `fontWeight` is only set for the system font (Android picks the
+ * wrong file when both are set).
+ */
+export declare function fontStyle(family: FontFamily, weight: number, source: FontSource): {
+    fontWeight: "400";
+    fontFamily?: undefined;
+} | {
+    fontFamily: string | undefined;
+    fontWeight?: undefined;
+};
+//# sourceMappingURL=fonts.d.ts.map

package/lib/typescript/theme/fonts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fonts.d.ts","sourceRoot":"","sources":["../../../src/theme/fonts.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,UAAU;;;;;;;;;CAStB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AACrD,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;AAiB5C;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU;gBACd,KAAK;;;;;EAGtE"}

package/lib/typescript/theme/haptics.d.ts

@@ -0,0 +1,3 @@
+export type HapticToken = 'selection' | 'toggleOn' | 'toggleOff' | 'confirm' | 'reject' | 'warning' | 'snap';
+export declare function playHaptic(token: HapticToken): void;
+//# sourceMappingURL=haptics.d.ts.map

package/lib/typescript/theme/haptics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"haptics.d.ts","sourceRoot":"","sources":["../../../src/theme/haptics.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,WAAW,GACrB,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAqBrF,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CA6BnD"}

package/lib/typescript/theme/navigation.d.ts

@@ -0,0 +1,158 @@
+import { type NexubTheme } from './ThemeProvider.js';
+/** Native stack `screenOptions`: large titles on a surface-coloured native header, Nexub type and tint. */
+export declare function nexubStackOptions(theme: NexubTheme): {
+    headerLargeTitle: boolean;
+    headerTransparent: boolean;
+    headerShadowVisible: boolean;
+    headerLargeTitleShadowVisible: boolean;
+    headerTintColor: string;
+    headerStyle: {
+        backgroundColor: string;
+    };
+    headerTitleStyle: {
+        fontWeight: "400";
+        fontFamily?: undefined;
+        color: string;
+    } | {
+        fontFamily: string | undefined;
+        fontWeight?: undefined;
+        color: string;
+    };
+    headerLargeTitleStyle: {
+        fontWeight: "400";
+        fontFamily?: undefined;
+        color: string;
+    } | {
+        fontFamily: string | undefined;
+        fontWeight?: undefined;
+        color: string;
+    };
+    contentStyle: {
+        backgroundColor: string;
+    };
+};
+/** React Navigation `theme` (also Expo Router's ThemeProvider). */
+export declare function nexubNavigationTheme(theme: NexubTheme): {
+    dark: boolean;
+    colors: {
+        primary: string;
+        background: string;
+        card: string;
+        text: string;
+        border: string;
+        notification: string;
+    };
+    fonts: {
+        regular: {
+            fontFamily: string;
+            fontWeight: "400";
+        };
+        medium: {
+            fontFamily: string;
+            fontWeight: "400";
+        };
+        bold: {
+            fontFamily: string;
+            fontWeight: "400";
+        };
+        heavy: {
+            fontFamily: string;
+            fontWeight: "400";
+        };
+    };
+};
+/** Colours for native tab bars (Expo Router NativeTabs / react-native-bottom-tabs). */
+export declare function nexubTabsOptions(theme: NexubTheme): {
+    tintColor: string;
+    inactiveTintColor: string;
+    backgroundColor: string;
+    badgeBackgroundColor: string;
+    labelStyle: {
+        fontSize: number;
+        fontWeight: "400";
+        fontFamily?: undefined;
+    } | {
+        fontSize: number;
+        fontFamily: string | undefined;
+        fontWeight?: undefined;
+    };
+};
+/** All three for the current theme: `const nav = useNexubNavigation()`. */
+export declare function useNexubNavigation(): {
+    stack: {
+        headerLargeTitle: boolean;
+        headerTransparent: boolean;
+        headerShadowVisible: boolean;
+        headerLargeTitleShadowVisible: boolean;
+        headerTintColor: string;
+        headerStyle: {
+            backgroundColor: string;
+        };
+        headerTitleStyle: {
+            fontWeight: "400";
+            fontFamily?: undefined;
+            color: string;
+        } | {
+            fontFamily: string | undefined;
+            fontWeight?: undefined;
+            color: string;
+        };
+        headerLargeTitleStyle: {
+            fontWeight: "400";
+            fontFamily?: undefined;
+            color: string;
+        } | {
+            fontFamily: string | undefined;
+            fontWeight?: undefined;
+            color: string;
+        };
+        contentStyle: {
+            backgroundColor: string;
+        };
+    };
+    theme: {
+        dark: boolean;
+        colors: {
+            primary: string;
+            background: string;
+            card: string;
+            text: string;
+            border: string;
+            notification: string;
+        };
+        fonts: {
+            regular: {
+                fontFamily: string;
+                fontWeight: "400";
+            };
+            medium: {
+                fontFamily: string;
+                fontWeight: "400";
+            };
+            bold: {
+                fontFamily: string;
+                fontWeight: "400";
+            };
+            heavy: {
+                fontFamily: string;
+                fontWeight: "400";
+            };
+        };
+    };
+    tabs: {
+        tintColor: string;
+        inactiveTintColor: string;
+        backgroundColor: string;
+        badgeBackgroundColor: string;
+        labelStyle: {
+            fontSize: number;
+            fontWeight: "400";
+            fontFamily?: undefined;
+        } | {
+            fontSize: number;
+            fontFamily: string | undefined;
+            fontWeight?: undefined;
+        };
+    };
+};
+//# sourceMappingURL=navigation.d.ts.map

package/lib/typescript/theme/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../src/theme/navigation.ts"],"names":[],"mappings":"AAGA,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,oBAAiB,CAAC;AAE5D,2GAA2G;AAC3G,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAelD;AAED,mEAAmE;AACnE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU;;;;;;;;;;;;;wBAMlB,KAAK;;;;wBAAL,KAAK;;;;wBAAL,KAAK;;;;wBAAL,KAAK;;;EAexC;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU;;;;;;;;;;;;;;EASjD;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BA9BE,KAAK;;;;4BAAL,KAAK;;;;4BAAL,KAAK;;;;4BAAL,KAAK;;;;;;;;;;;;;;;;;;;EAqCxC"}

package/package.json

@@ -1,6 +1,141 @@
 {
   "name": "@nexub/react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.1.0",
+  "description": "React Native components for Nexub Design System — native chrome, Nexub content. Same tokens, brands and prop names as @nexub/react, for Expo and bare React Native apps.",
+  "license": "MIT",
+  "homepage": "https://github.com/Nexub-AI/nexub-ds#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Nexub-AI/nexub-ds.git",
+    "directory": "packages/react-native"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "components",
+    "design-system",
+    "nexub"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "lib",
+    "!src/__tests__"
+  ],
+  "sideEffects": false,
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./lib/typescript/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./patterns": {
+      "source": "./src/patterns/index.ts",
+      "types": "./lib/typescript/patterns/index.d.ts",
+      "default": "./lib/module/patterns/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "dependencies": {
+    "@expo-google-fonts/geist-mono": "^0.4.3",
+    "@expo-google-fonts/inter": "^0.4.2",
+    "@expo-google-fonts/plus-jakarta-sans": "^0.4.2",
+    "lucide-react-native": "^1.64.0",
+    "@nexub/core": "2.1.0",
+    "@nexub/icons": "2.1.0",
+    "@nexub/tokens": "2.1.0"
+  },
+  "peerDependencies": {
+    "expo-glass-effect": ">=57.0.0",
+    "expo-haptics": ">=57.0.0",
+    "react": ">=19.1.0",
+    "react-native": ">=0.86.0",
+    "react-native-reanimated": ">=4.5.0",
+    "react-native-safe-area-context": ">=5.6.0",
+    "react-native-svg": ">=15.0.0",
+    "@react-native-community/datetimepicker": ">=8.4.0",
+    "expo-screen-capture": ">=57.0.0"
+  },
+  "peerDependenciesMeta": {
+    "expo-glass-effect": {
+      "optional": true
+    },
+    "expo-haptics": {
+      "optional": true
+    },
+    "@react-native-community/datetimepicker": {
+      "optional": true
+    },
+    "expo-screen-capture": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react-native": "^14.1.0",
+    "@types/jest": "^30.0.0",
+    "@types/react": "~19.3.0",
+    "expo": "~58.0.21",
+    "expo-glass-effect": "~58.0.5",
+    "expo-haptics": "~58.0.7",
+    "jest": "^30.2.0",
+    "jest-expo": "~58.0.13",
+    "react": "19.3.0",
+    "react-native": "0.88.1",
+    "react-native-builder-bob": "^0.44.1",
+    "react-native-reanimated": "4.7.1",
+    "react-native-safe-area-context": "~5.10.1",
+    "react-native-svg": "15.16.0",
+    "react-native-worklets": "0.13.0",
+    "typescript": "^5.9.3",
+    "@react-native-community/datetimepicker": "9.2.1",
+    "expo-screen-capture": "~58.0.6"
+  },
+  "jest": {
+    "preset": "jest-expo",
+    "roots": [
+      "<rootDir>/src"
+    ],
+    "setupFiles": [
+      "<rootDir>/jest.setup.js"
+    ],
+    "transformIgnorePatterns": [
+      "node_modules/(?!(\\.pnpm|((jest-)?react-native|@react-native(-community)?)|expo(nent)?|@expo(nent)?/.*|@expo-google-fonts/.*|react-navigation|@react-navigation/.*|react-native-svg|lucide-react-native|@nexub/.*|@material/.*))"
+    ],
+    "transform": {
+      "^.+\\.mjs$": "babel-jest"
+    },
+    "moduleNameMapper": {
+      "^react$": "<rootDir>/node_modules/react",
+      "^react/(.*)$": "<rootDir>/node_modules/react/$1"
+    }
+  },
+  "scripts": {
+    "build": "bob build",
+    "clean": "rm -rf lib",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "jest"
+  }
 }

package/src/components/actions.tsx

@@ -0,0 +1,259 @@
+import * as React from 'react';
+import { ActivityIndicator, View, type StyleProp, type ViewStyle } from 'react-native';
+import type { ControlSize, ToneValue } from '@nexub/core';
+import type { NativeIconProps } from '@nexub/icons/native';
+import { Pressable, type PressableProps } from '../primitives/Pressable';
+import { Surface } from '../primitives/Surface';
+import { Text } from '../primitives/Text';
+import { useTheme, type RoleName } from '../theme/ThemeProvider';
+import type { HapticToken } from '../theme/haptics';
+import { TONE_ROLES, controlHeight, disabledOpacity, hitSlopFor } from './shared';
+
+export type ButtonVariant = 'filled' | 'tonal' | 'outlined' | 'text' | 'glass';
+
+// [container role | undefined, content role]
+const VARIANT: Record<ButtonVariant, [RoleName | undefined, RoleName]> = {
+  filled: ['primary', 'on-primary'],
+  tonal: ['secondary-container', 'on-secondary-container'],
+  outlined: [undefined, 'on-surface'],
+  text: [undefined, 'primary'],
+  glass: [undefined, 'on-surface'],
+};
+
+const LABEL: Record<ControlSize, 'label-md' | 'label-lg' | 'title-md'> = {
+  xs: 'label-md',
+  sm: 'label-md',
+  md: 'label-lg',
+  lg: 'label-lg',
+  xl: 'title-md',
+};
+const PAD: Record<ControlSize, number> = { xs: 10, sm: 14, md: 20, lg: 24, xl: 28 };
+const ICON: Record<ControlSize, NativeIconProps['size']> = {
+  xs: 'xs',
+  sm: 'sm',
+  md: 'sm',
+  lg: 'md',
+  xl: 'md',
+};
+
+export interface ButtonProps extends Omit<PressableProps, 'children'> {
+  children: React.ReactNode;
+  /** @default 'filled' */
+  variant?: ButtonVariant;
+  /** Solid semantic or product colour (overrides the variant colour). */
+  tone?: ToneValue;
+  /** The control ladder. Primary actions on mobile use 'lg' (48). @default 'md' */
+  size?: ControlSize;
+  /** Shows a spinner, blocks presses and announces `loadingLabel`. */
+  loading?: boolean;
+  loadingLabel?: string;
+  fullWidth?: boolean;
+  leadingIcon?: React.ComponentType<NativeIconProps>;
+  trailingIcon?: React.ComponentType<NativeIconProps>;
+}
+
+/** Capsule button. One `filled` (or toned) action per screen; the rest tonal/outlined/text. */
+export function Button({
+  children,
+  variant = 'filled',
+  tone,
+  size = 'md',
+  loading,
+  loadingLabel,
+  fullWidth,
+  leadingIcon: Leading,
+  trailingIcon: Trailing,
+  disabled,
+  style,
+  accessibilityLabel,
+  ...rest
+}: ButtonProps) {
+  const theme = useTheme();
+  const { roles } = theme;
+  const [bgRole, fgRole] = tone ? TONE_ROLES[tone] : VARIANT[variant];
+  const height = controlHeight(theme, size);
+  const fg = roles[fgRole];
+  const inactive = disabled || loading;
+  const label = typeof children === 'string' ? children : undefined;
+
+  const body = (
+    <View
+      style={{
+        flexDirection: 'row',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: 8,
+        opacity: disabled ? disabledOpacity(theme) : 1,
+      }}
+    >
+      {loading ? (
+        <ActivityIndicator size="small" color={fg} />
+      ) : (
+        Leading && <Leading size={ICON[size]} color={fg} />
+      )}
+      {typeof children === 'string' ? (
+        <Text variant={LABEL[size]} style={{ color: fg }} numberOfLines={1}>
+          {children}
+        </Text>
+      ) : (
+        children
+      )}
+      {!loading && Trailing && <Trailing size={ICON[size]} color={fg} />}
+    </View>
+  );
+
+  const shape: StyleProp<ViewStyle> = [
+    {
+      height,
+      paddingHorizontal: PAD[size],
+      borderRadius: theme.tokens.shape.control,
+      justifyContent: 'center',
+      alignSelf: fullWidth ? 'stretch' : 'flex-start',
+      backgroundColor: bgRole ? roles[bgRole] : 'transparent',
+    },
+    variant === 'outlined' && !tone && { borderWidth: 1, borderColor: roles['outline-variant'] },
+    disabled && bgRole && { backgroundColor: roles['on-surface'] + '1f' }, // disabled-container 12%
+    style,
+  ];
+
+  return (
+    <Pressable
+      accessibilityLabel={accessibilityLabel ?? (loading && loadingLabel ? loadingLabel : label)}
+      accessibilityState={{ disabled: !!inactive, busy: !!loading }}
+      disabled={inactive}
+      hitSlop={hitSlopFor(height)}
+      stateLayer={fgRole}
+      style={
+        variant === 'glass' && !tone ? { alignSelf: fullWidth ? 'stretch' : 'flex-start' } : shape
+      }
+      {...rest}
+    >
+      {variant === 'glass' && !tone ? (
+        <Surface
+          material="glass"
+          radius="control"
+          style={[{ height, paddingHorizontal: PAD[size], justifyContent: 'center' }, style]}
+        >
+          {body}
+        </Surface>
+      ) : (
+        body
+      )}
+    </Pressable>
+  );
+}
+
+export interface IconButtonProps extends Omit<PressableProps, 'children'> {
+  icon: React.ComponentType<NativeIconProps>;
+  /** Required: the accessible name (what it does, not "button"). */
+  label: string;
+  /** @default 'text' */
+  variant?: ButtonVariant;
+  tone?: ToneValue;
+  /** @default 'md' */
+  size?: ControlSize;
+  /** Toggle state for icon toggles (favourite, mute). */
+  selected?: boolean;
+  haptic?: HapticToken;
+}
+
+/** Circular icon-only button; always 44pt+ to touch. */
+export function IconButton({
+  icon: Glyph,
+  label,
+  variant = 'text',
+  tone,
+  size = 'md',
+  selected,
+  disabled,
+  style,
+  ...rest
+}: IconButtonProps) {
+  const theme = useTheme();
+  const [bgRole, fgRole] = tone ? TONE_ROLES[tone] : VARIANT[variant];
+  const fgSelected: RoleName = selected
+    ? 'primary'
+    : variant === 'text' && !tone
+      ? 'on-surface-variant'
+      : fgRole;
+  const height = controlHeight(theme, size);
+  return (
+    <Pressable
+      accessibilityLabel={label}
+      accessibilityState={{ disabled: !!disabled, selected }}
+      disabled={disabled}
+      hitSlop={hitSlopFor(height)}
+      stateLayer={fgRole}
+      style={[
+        {
+          width: height,
+          height,
+          borderRadius: height / 2,
+          alignItems: 'center',
+          justifyContent: 'center',
+          backgroundColor: bgRole ? theme.roles[bgRole] : 'transparent',
+          opacity: disabled ? disabledOpacity(theme) : 1,
+        },
+        variant === 'outlined' && { borderWidth: 1, borderColor: theme.roles['outline-variant'] },
+        style,
+      ]}
+      {...rest}
+    >
+      <Glyph
+        size={ICON[size] === 'xs' ? 'sm' : size === 'xl' ? 'lg' : 'md'}
+        color={theme.roles[fgSelected]}
+      />
+    </Pressable>
+  );
+}
+
+export interface ButtonGroupProps {
+  children: React.ReactNode;
+  /** 'stack' puts actions full-width in a column (bottom of forms). @default 'row' */
+  direction?: 'row' | 'stack';
+  style?: StyleProp<ViewStyle>;
+}
+
+/** Related actions together. In a stack, put the primary action first. */
+export function ButtonGroup({ children, direction = 'row', style }: ButtonGroupProps) {
+  const { tokens } = useTheme();
+  return (
+    <View
+      style={[
+        direction === 'row'
+          ? { flexDirection: 'row', flexWrap: 'wrap', gap: tokens.spacing[2] }
+          : { gap: tokens.spacing[3], alignItems: 'stretch' },
+        style,
+      ]}
+    >
+      {direction === 'stack'
+        ? React.Children.map(children, (c) =>
+            React.isValidElement<ButtonProps>(c) ? React.cloneElement(c, { fullWidth: true }) : c,
+          )
+        : children}
+    </View>
+  );
+}
+
+export interface LinkProps extends Omit<PressableProps, 'children'> {
+  children: string;
+}
+
+/** Inline text action. Opens nothing by itself: pass `onPress` (e.g. router.push / Linking.openURL). */
+export function Link({ children, style, ...rest }: LinkProps) {
+  return (
+    <Pressable
+      accessibilityRole="link"
+      accessibilityLabel={children}
+      stateLayer={false}
+      pressScale={false}
+      hitSlop={8}
+      style={style}
+      {...rest}
+    >
+      <Text variant="label-lg" color="primary" style={{ textDecorationLine: 'underline' }}>
+        {children}
+      </Text>
+    </Pressable>
+  );
+}