august-design-system/dist/hooks/index.d.mts

A comprehensive React Native design system following Apple Human Interface Guidelines

import { StyleSheet } from 'react-native';
import { T as Theme, B as Breakpoint, R as ResponsiveValue } from '../theme.types-BF73i5o1.mjs';
import { T as TypographyStyle } from '../tokens.types-kLhwMiT-.mjs';
import { b as animationPresets } from '../animation-C9i2F2sT.mjs';

/**
 * 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 };