august-design-system
Version:
A comprehensive React Native design system following Apple Human Interface Guidelines
468 lines (460 loc) • 13.3 kB
TypeScript
import { StyleSheet } from 'react-native';
import { T as Theme, B as Breakpoint, R as ResponsiveValue } from '../theme.types-CYmxw5XZ.js';
import { T as TypographyStyle } from '../tokens.types-kLhwMiT-.js';
import { b as animationPresets } from '../animation-4uGVCbyy.js';
/**
* AugustDesignSystem - useThemedStyles Hook
*
* Hook for creating memoized styles based on theme.
* Automatically updates styles when theme changes.
*/
/**
* Style creator function type.
*/
type StyleCreator<T extends StyleSheet.NamedStyles<T>> = (theme: Theme) => T;
/**
* Hook that creates memoized styles based on the current theme.
*
* Styles are automatically recreated when the theme changes (e.g., light/dark mode toggle).
* Uses StyleSheet.create internally for performance optimization.
*
* @param styleCreator - Function that receives theme and returns style object
* @returns Memoized StyleSheet object
*
* @example
* ```tsx
* const styles = useThemedStyles((theme) => ({
* container: {
* backgroundColor: theme.colors.background.primary,
* padding: theme.spacing.lg,
* },
* title: {
* ...theme.typography.headline,
* color: theme.colors.label.primary,
* },
* button: {
* backgroundColor: theme.colors.interactive.tint,
* borderRadius: theme.radius.sm,
* height: theme.sizes.button.md,
* },
* }));
*
* return (
* <View style={styles.container}>
* <Text style={styles.title}>Hello</Text>
* </View>
* );
* ```
*/
declare function useThemedStyles<T extends StyleSheet.NamedStyles<T>>(styleCreator: StyleCreator<T>): T;
/**
* Hook for creating a single themed style object.
* Useful when you only need one style object.
*
* @param styleCreator - Function that receives theme and returns style
* @returns Memoized style object
*
* @example
* ```tsx
* const containerStyle = useThemedStyle((theme) => ({
* backgroundColor: theme.colors.background.primary,
* padding: theme.spacing.lg,
* }));
*
* return <View style={containerStyle} />;
* ```
*/
declare function useThemedStyle<T extends Record<string, unknown>>(styleCreator: (theme: Theme) => T): T;
/**
* Factory function to create a themed styles hook for a component.
* Useful for defining styles outside of components.
*
* @param styleCreator - Function that receives theme and returns style object
* @returns Hook that returns the themed styles
*
* @example
* ```tsx
* // Define outside component
* const useButtonStyles = createThemedStyles((theme) => ({
* container: {
* backgroundColor: theme.colors.interactive.tint,
* borderRadius: theme.radius.sm,
* height: theme.sizes.button.md,
* paddingHorizontal: theme.spacing.lg,
* justifyContent: 'center',
* alignItems: 'center',
* },
* label: {
* ...theme.typography.headline,
* color: '#FFFFFF',
* },
* disabled: {
* opacity: theme.opacity.disabled,
* },
* }));
*
* // Use in component
* function Button({ title, disabled }) {
* const styles = useButtonStyles();
* return (
* <Pressable style={[styles.container, disabled && styles.disabled]}>
* <Text style={styles.label}>{title}</Text>
* </Pressable>
* );
* }
* ```
*/
declare function createThemedStyles<T extends StyleSheet.NamedStyles<T>>(styleCreator: StyleCreator<T>): () => T;
/**
* Combines multiple style objects, filtering out falsy values.
* Type-safe alternative to array syntax.
*
* @param styles - Style objects to combine
* @returns Combined style object
*
* @example
* ```tsx
* const combinedStyle = combineStyles(
* styles.base,
* isActive && styles.active,
* isDisabled && styles.disabled
* );
* ```
*/
declare function combineStyles<T>(...styles: (T | false | null | undefined)[]): T[];
/**
* Creates a conditional style object.
*
* @param condition - Condition to check
* @param trueStyle - Style to return if condition is true
* @param falseStyle - Style to return if condition is false (optional)
* @returns Selected style or undefined
*/
declare function conditionalStyle<T>(condition: boolean, trueStyle: T, falseStyle?: T): T | undefined;
/**
* AugustDesignSystem - useResponsive Hook
*
* Hooks for responsive design based on device dimensions.
*/
/**
* Hook that returns the current breakpoint based on screen width.
*
* @returns Current breakpoint key
*
* @example
* ```tsx
* function MyComponent() {
* const breakpoint = useBreakpoint();
*
* return (
* <View>
* {breakpoint === 'xs' && <MobileLayout />}
* {breakpoint === 'lg' && <TabletLayout />}
* </View>
* );
* }
* ```
*/
declare function useBreakpoint(): Breakpoint;
/**
* Hook that resolves a responsive value based on current breakpoint.
*
* @param value - Single value or breakpoint-mapped values
* @returns Resolved value for current breakpoint
*
* @example
* ```tsx
* function MyComponent() {
* // Single value - same for all breakpoints
* const padding1 = useResponsiveValue(16);
*
* // Responsive value - different per breakpoint
* const padding2 = useResponsiveValue({
* xs: 8,
* sm: 12,
* md: 16,
* lg: 24,
* xl: 32,
* });
*
* // Partial responsive value - inherits from smaller breakpoints
* const padding3 = useResponsiveValue({
* xs: 8,
* md: 16,
* // lg and xl will use md's value (16)
* });
*
* return <View style={{ padding: padding2 }} />;
* }
* ```
*/
declare function useResponsiveValue<T>(value: ResponsiveValue<T>): T;
/**
* Device type classification.
*/
type DeviceType = 'phone' | 'tablet';
/**
* Hook that returns the device type based on screen width.
*
* @returns Device type ('phone' | 'tablet')
*
* @example
* ```tsx
* function MyComponent() {
* const deviceType = useDeviceType();
* const isTablet = deviceType === 'tablet';
*
* return isTablet ? <SidebarLayout /> : <StackLayout />;
* }
* ```
*/
declare function useDeviceType(): DeviceType;
/**
* Hook that checks if current breakpoint matches or is larger than specified.
*
* @param targetBreakpoint - Minimum breakpoint to match
* @returns True if current breakpoint is >= target
*
* @example
* ```tsx
* function MyComponent() {
* const isTablet = useIsBreakpoint('lg');
* const isLargePhone = useIsBreakpoint('md');
*
* return (
* <View style={{ flexDirection: isTablet ? 'row' : 'column' }}>
* {children}
* </View>
* );
* }
* ```
*/
declare function useIsBreakpoint(targetBreakpoint: Breakpoint): boolean;
/**
* Screen dimension info with additional computed values.
*/
interface ScreenDimensions {
width: number;
height: number;
isPortrait: boolean;
isLandscape: boolean;
aspectRatio: number;
}
/**
* Hook that provides screen dimensions with computed values.
*
* @returns Screen dimension information
*
* @example
* ```tsx
* function MyComponent() {
* const { width, isPortrait, aspectRatio } = useScreenDimensions();
*
* return (
* <Image
* style={{
* width: width * 0.8,
* aspectRatio: isPortrait ? 1 : 16/9,
* }}
* />
* );
* }
* ```
*/
declare function useScreenDimensions(): ScreenDimensions;
/**
* Creates a responsive style object.
* Helper for building styles that change at breakpoints.
*
* @param styles - Breakpoint-mapped style objects
* @returns Function that resolves style for given breakpoint
*
* @example
* ```tsx
* const getContainerStyle = responsiveStyle({
* xs: { padding: 8 },
* sm: { padding: 12 },
* md: { padding: 16, flexDirection: 'row' },
* lg: { padding: 24, flexDirection: 'row' },
* });
*
* function MyComponent() {
* const breakpoint = useBreakpoint();
* return <View style={getContainerStyle(breakpoint)} />;
* }
* ```
*/
declare function responsiveStyle<T>(styles: Partial<Record<Breakpoint, T>>): (breakpoint: Breakpoint) => T | undefined;
/**
* AugustDesignSystem - Accessibility Hooks
*
* Hooks for accessibility features following Apple's accessibility guidelines.
* Supports reduced motion, dynamic type, and other iOS accessibility settings.
*/
/**
* Hook that detects if the user has enabled "Reduce Motion" setting.
* When true, animations should be simplified or removed.
*
* @returns Boolean indicating if reduced motion is enabled
*
* @example
* ```tsx
* function AnimatedComponent() {
* const prefersReducedMotion = useReducedMotion();
*
* const animationConfig = prefersReducedMotion
* ? { duration: 0 }
* : { duration: 300, easing: 'spring' };
*
* return <Animated.View style={animatedStyle} />;
* }
* ```
*/
declare function useReducedMotion(): boolean;
/**
* Animation configuration that respects reduced motion preference.
*/
interface AccessibleAnimationConfig {
duration: number;
useNativeDriver: boolean;
isReduced: boolean;
}
/**
* Hook that provides animation configuration respecting reduced motion.
*
* @param preset - Animation preset name
* @returns Animation configuration
*
* @example
* ```tsx
* function Modal() {
* const { duration, isReduced } = useAccessibleAnimation('modalEnter');
*
* const enterAnimation = useCallback(() => {
* Animated.timing(opacity, {
* toValue: 1,
* duration,
* useNativeDriver: true,
* }).start();
* }, [duration]);
*
* return <Animated.View style={{ opacity }} />;
* }
* ```
*/
declare function useAccessibleAnimation(preset: keyof typeof animationPresets): AccessibleAnimationConfig;
/**
* Hook that detects if a screen reader (VoiceOver on iOS) is active.
*
* @returns Boolean indicating if screen reader is enabled
*
* @example
* ```tsx
* function ImageGallery() {
* const screenReaderEnabled = useScreenReader();
*
* // Provide more detailed descriptions when screen reader is active
* const imageDescription = screenReaderEnabled
* ? 'Photo showing a sunset over the ocean with orange and purple colors'
* : 'Sunset photo';
*
* return <Image accessibilityLabel={imageDescription} />;
* }
* ```
*/
declare function useScreenReader(): boolean;
/**
* Hook that detects if the user has enabled "Bold Text" setting.
*
* @returns Boolean indicating if bold text is enabled
*
* @example
* ```tsx
* function Text({ children }) {
* const boldTextEnabled = useBoldText();
* const fontWeight = boldTextEnabled ? '700' : '400';
*
* return <RNText style={{ fontWeight }}>{children}</RNText>;
* }
* ```
*/
declare function useBoldText(): boolean;
/**
* Dynamic type scale factors.
* iOS allows users to scale text from ~82% to ~310% of default size.
*/
type DynamicTypeSize = 'xSmall' | 'small' | 'medium' | 'large' | 'xLarge' | 'xxLarge' | 'xxxLarge' | 'accessibility1' | 'accessibility2' | 'accessibility3' | 'accessibility4' | 'accessibility5';
/**
* Hook that provides font scale factor for Dynamic Type support.
*
* @returns Current font scale factor
*
* @example
* ```tsx
* function ScaledText({ style, children }) {
* const fontScale = useDynamicType();
*
* return (
* <Text style={[style, { fontSize: style.fontSize * fontScale }]}>
* {children}
* </Text>
* );
* }
* ```
*/
declare function useDynamicType(): number;
/**
* Hook that scales typography styles based on Dynamic Type setting.
*
* @param baseStyle - Base typography style
* @param options - Scaling options
* @returns Scaled typography style
*
* @example
* ```tsx
* function Heading({ children }) {
* const { theme } = useTheme();
* const style = useScaledTypography(theme.typography.headline, {
* maxScale: 1.5, // Limit scaling to 150%
* });
*
* return <Text style={style}>{children}</Text>;
* }
* ```
*/
declare function useScaledTypography(baseStyle: TypographyStyle, options?: {
maxScale?: number;
minScale?: number;
}): TypographyStyle;
/**
* Hook that detects if the user has enabled increased contrast.
* Note: This setting affects system UI but apps should respect it too.
*
* @returns Boolean indicating if high contrast is enabled
*/
declare function useHighContrast(): boolean;
/**
* Announces a message to screen reader users.
*
* @param message - Message to announce
*
* @example
* ```tsx
* function SubmitButton({ onPress }) {
* const handlePress = async () => {
* await onPress();
* announceForAccessibility('Form submitted successfully');
* };
*
* return <Button onPress={handlePress} title="Submit" />;
* }
* ```
*/
declare function announceForAccessibility(message: string): void;
/**
* Sets focus to a specific accessibility element.
*
* @param reactTag - React native tag of the element
*/
declare function setAccessibilityFocus(reactTag: number | null): void;
export { type AccessibleAnimationConfig, type DeviceType, type DynamicTypeSize, type ScreenDimensions, announceForAccessibility, combineStyles, conditionalStyle, createThemedStyles, responsiveStyle, setAccessibilityFocus, useAccessibleAnimation, useBoldText, useBreakpoint, useDeviceType, useDynamicType, useHighContrast, useIsBreakpoint, useReducedMotion, useResponsiveValue, useScaledTypography, useScreenDimensions, useScreenReader, useThemedStyle, useThemedStyles };