react-native-unistyles 1.0.0-beta.1

package/src/utils/breakpoints.ts

@@ -0,0 +1,140 @@
+import { throwError } from './common'
+import type { ScreenSize } from '../types'
+import { getKeyForCustomMediaQuery, isMediaQuery } from './mediaQueries'
+
+/**
+ * Sorts the breakpoints object based on its numeric values in ascending order and validates them.
+ *
+ * This function takes an object where keys represent breakpoint names and values are numeric.
+ * It returns a new object with the same keys but sorted based on their corresponding numeric values.
+ * Additionally, it validates that:
+ * 1. The first breakpoint starts with a value of 0.
+ * 2. No duplicate breakpoint values exist.
+ *
+ * If the validation fails, appropriate error messages are logged to the console.
+ *
+ * @template B - An object type where keys are strings and values are numbers.
+ * @param {B} breakpoints - The breakpoints object to be sorted and validated.
+ * @returns {B} A new object with sorted and validated breakpoints.
+ *
+ * @example
+ * const input = { md: 768, lg: 1024, sm: 0 }
+ * sortAndValidateBreakpoints(input) // returns { sm: 0, md: 768, lg: 1024 }
+ */
+export const sortAndValidateBreakpoints = <B extends Record<string, number>>(breakpoints: B): B => {
+    const sortedPairs = Object
+        .entries(breakpoints)
+        .sort((breakpoint1, breakpoint2) => {
+            const [, value1] = breakpoint1
+            const [, value2] = breakpoint2
+
+            return value1 - value2
+        })
+
+    const sortedBreakpoints =  Object.freeze(Object.fromEntries(sortedPairs)) as B
+    const breakpointValues = Object.values(sortedBreakpoints)
+    const [firstBreakpoint] = breakpointValues
+
+    if (firstBreakpoint !== 0) {
+        throwError('first breakpoint must start with 0')
+    }
+
+    if (breakpointValues.length !== new Set(breakpointValues).size) {
+        throwError('breakpoint values are duplicated')
+    }
+
+    return sortedBreakpoints
+}
+
+/**
+ * Determines the appropriate breakpoint key for a given screen width based on provided breakpoints.
+ *
+ * This function takes a screen width and an object of breakpoints. It returns the key of the breakpoint
+ * that the screen width falls into. The breakpoints are assumed to be sorted in ascending order.
+ *
+ * @template B - An object type where keys are strings and values are numbers representing screen widths.
+ * @param {number} width - The screen width to determine the breakpoint for.
+ * @param {B} breakpoints - The breakpoints object to use for determination.
+ * @returns {keyof B & string} The key of the breakpoint that the screen width falls into.
+ *
+ * @example
+ * const breakpoints = { sm: 0, md: 768, lg: 1024 }
+ * getBreakpointFromScreenWidth(800, breakpoints) // returns 'md'
+ */
+export const getBreakpointFromScreenWidth = <B extends Record<string, number>>(width: number, breakpoints: B): keyof B & string => {
+    const [key] = Object
+        .entries(breakpoints)
+        .find(([, value], index, otherBreakpoints) => {
+            const minVal = value
+            const maxVal = otherBreakpoints[index + 1]?.[1]
+
+            if (!maxVal) {
+                return true
+            }
+
+            return width >= minVal && width < maxVal
+        }) as [keyof B & string, number]
+
+    return key
+}
+
+/**
+ * Retrieves the value associated with a given breakpoint or custom media query based on the provided screen size.
+ *
+ * The function first checks for custom media queries. If a matching custom media query is found, its associated value is returned.
+ * If no custom media query matches, the function then checks for a direct breakpoint match.
+ * If there's no direct breakpoint match, the function simulates CSS cascading to find the closest matching breakpoint.
+ *
+ * @template B - An object type where keys represent breakpoint names and values represent breakpoint values.
+ *
+ * @param {Record<keyof B & string, string | number>} value - An object containing values associated with breakpoints or custom media queries.
+ * @param {keyof B & string} breakpoint - The breakpoint name to check against.
+ * @param {ScreenSize} screenSize - An object representing the screen size to be checked against the media queries.
+ * @param {B} breakpoints - An object representing the defined breakpoints.
+ *
+ * @returns {string | number | undefined} Returns the value associated with the matching breakpoint or custom media query, or `undefined` if no match is found.
+ *
+ * @example
+ *
+ * const values = { ':w[200]': 'value1', sm: 'value2', md: 'value3' }
+ * const screenSize = { width: 250, height: 400 }
+ * const breakpoints = { sm: 300, md: 600, lg: 900 }
+ *
+ * getValueForBreakpoint(values, 'sm', screenSize, breakpoints); // 'value1'
+ */
+export const getValueForBreakpoint = <B extends Record<string, number>>(value: Record<keyof B & string, string | number | undefined>, breakpoint: keyof B & string, screenSize: ScreenSize, breakpoints: B) => {
+    // the highest priority is for custom media queries
+    const customMediaQueries = Object
+        .entries(value)
+        .filter(([key]) => isMediaQuery(key))
+    const customMediaQueryKey = getKeyForCustomMediaQuery(customMediaQueries, screenSize)
+
+    if (customMediaQueryKey && customMediaQueryKey in value) {
+        return value[customMediaQueryKey]
+    }
+
+    // if no custom media query, or didn't match, proceed with defined breakpoints
+    const unifiedKey = breakpoint.toLowerCase()
+    const directBreakpoint = value[unifiedKey]
+
+    // if there is a direct key like 'sm' or 'md', or value for this key exists but its undefined
+    if (directBreakpoint || (unifiedKey in value)) {
+        return directBreakpoint
+    }
+
+    // there is no direct hit for breakpoint nor media-query, so let's simulate CSS cascading
+    const allBreakpoints = Object
+        .entries(breakpoints)
+        .map(([key, bpValue]) => [key.toLowerCase(), bpValue])
+
+    const currentBreakpoint = allBreakpoints
+        .findIndex(([key]) => key === unifiedKey)
+
+    const availableBreakpoints = allBreakpoints
+        .filter(([key], index) => index < currentBreakpoint && key && key in value)
+        .map(([key]) => key)
+
+    return allBreakpoints.length > 0
+        ? value[availableBreakpoints[availableBreakpoints.length - 1] as keyof B & string]
+        : undefined
+}

package/src/utils/common.ts

@@ -0,0 +1,3 @@
+export const throwError = (message: string) => {
+    throw new Error(`🦄 [react-native-unistyles]: ${message}`)
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export { getBreakpointFromScreenWidth, sortAndValidateBreakpoints } from './breakpoints'
+export { proxifyFunction, parseStyle } from './styles'

package/src/utils/mediaQueries.ts

@@ -0,0 +1,201 @@
+import type { ScreenSize } from '../types'
+
+/**
+ * Extracts numeric values from a coded string.
+ *
+ * The function is designed to process strings that have a format like "w[100,200]" or "h[300]".
+ * It removes characters 'w', 'h', '[', and ']' from the input string and then extracts the numbers.
+ *
+ * @param {string} codedValue - The input string to extract values from.
+ * @returns {Array<number>} An array of extracted numbers. Can contain one or two numbers based on the input format.
+ *
+ * @example
+ * extractValues("w[100,200]") // returns [100, 200]
+ * extractValues("h[300]")     // returns [300]
+ * extractValues("h[,300]")    // returns [0,300]
+ * extractValues("h[100,]")    // returns [100]
+ */
+export const extractValues = (codedValue: string): Array<number> => {
+    const [lh, rh] = codedValue
+        .replace(/[wh[\]]/g, '')
+        .split(',')
+
+    return rh
+        ? [Number(lh), Number(rh)]
+        : [Number(lh)]
+}
+
+/**
+ * Determines if the given screen size matches the specified breakpoint query.
+ *
+ * The function checks if the screen size (width and/or height) falls within the range
+ * specified by the breakpoint query. The query can specify width (using 'w'), height (using 'h'),
+ * or both.
+ *
+ * @param {string} query - The breakpoint query string. Examples: 'w[100,200]', 'h[300]', 'w[100,200]h[300,400]'.
+ * @param {ScreenSize} screenSize - The screen size to check against the breakpoint query.
+ * @returns {boolean} True if the screen size matches the breakpoint query, false otherwise.
+ *
+ * @example
+ * const screenSize = { width: 150, height: 350 }
+ * isWithinBreakpoint('w[100,200]', screenSize) // returns true
+ * isWithinBreakpoint('h[400]', screenSize)     // returns false
+ */
+export const isWithinBreakpoint = (query: string, screenSize: ScreenSize): boolean => {
+    if (query.includes('w') && query.includes('h')) {
+        return isWithinTheWidthAndHeight(query, screenSize)
+    }
+
+    if (query.charAt(0) === 'w') {
+        return isWithinTheWidth(query, screenSize.width)
+    }
+
+    if (query.charAt(0) === 'h') {
+        return isWithinTheHeight(query, screenSize.height)
+    }
+
+    return false
+}
+
+/**
+ * Determines if the given width matches the specified width range in the query.
+ *
+ * The function checks if the provided width falls within the range specified by the query.
+ * The query specifies a width range using a format like 'w[100,200]'. If only one value is provided,
+ * it's treated as a minimum width.
+ *
+ * @param {string} query - The width query string. Examples: 'w[100,200]' or 'w[100]'.
+ * @param {number} width - The width to check against the query.
+ * @returns {boolean} True if the width matches the query range, false otherwise.
+ *
+ * @example
+ * isWithinTheWidth('w[100,200]', 150) // returns true
+ * isWithinTheWidth('w[100]', 50)      // returns false
+ * isWithinTheWidth('w[100]', 150)     // returns true
+ */
+export const isWithinTheWidth = (query: string, width: number): boolean => {
+    const [minWidth, maxWidth] = extractValues(query) as [number, number | undefined]
+
+    if (maxWidth && width >= minWidth && width <= maxWidth) {
+        return true
+    }
+
+    return !maxWidth && width >= minWidth
+}
+
+/**
+ * Determines if the given height matches the specified height range in the query.
+ *
+ * The function checks if the provided height falls within the range specified by the query.
+ * The query specifies a height range using a format like 'h[100,200]'. If only one value is provided,
+ * it's treated as a minimum height.
+ *
+ * @param {string} query - The height query string. Examples: 'h[100,200]' or 'h[100]'.
+ * @param {number} height - The height to check against the query.
+ * @returns {boolean} True if the height matches the query range, false otherwise.
+ *
+ * @example
+ * isWithinTheHeight('h[100,200]', 150) // returns true
+ * isWithinTheHeight('h[100]', 50)      // returns false
+ * isWithinTheHeight('h[100]', 150)     // returns true
+ */
+export const isWithinTheHeight = (query: string, height: number): boolean => {
+    const [minHeight, maxHeight] = extractValues(query) as [number, number | undefined]
+
+    if (maxHeight && height >= minHeight && height <= maxHeight) {
+        return true
+    }
+
+    return !maxHeight && height >= minHeight
+}
+
+/**
+ * Determines if the given screen size matches both the specified width and height ranges in the query.
+ *
+ * The function checks if the provided screen size (both width and height) falls within the ranges
+ * specified by the query. The query can specify both width and height using a format like 'w[100,200]:h[300,400]'.
+ *
+ * @param {string} query - The combined width and height query string. Example: 'w[100,200]:h[300,400]'.
+ * @param {ScreenSize} screenSize - The screen size to check against the query.
+ * @returns {boolean} True if the screen size matches both the width and height ranges in the query, false otherwise.
+ *
+ * @example
+ * const screenSize = { width: 150, height: 350 }
+ * isWithinTheWidthAndHeight('w[100,200]:h[300,400]', screenSize) // returns true
+ * isWithinTheWidthAndHeight('w[100,200]:h[400,500]', screenSize) // returns false
+ */
+export const isWithinTheWidthAndHeight = (query: string, screenSize: ScreenSize): boolean => {
+    const result = query
+        .split(':')
+        .filter(Boolean)
+        .map(q => isWithinBreakpoint(q, screenSize))
+        .filter(Boolean)
+
+    return result.length === 2
+}
+
+/**
+ * Checks if the given query string is a valid custom media query.
+ *
+ * The valid custom media query formats include:
+ * - :w[200]
+ * - :w[0, 200]
+ * - :w[, 300]
+ * - :h[200]
+ * - :h[0, 500]
+ * - :h[,200]
+ * - :w[100, 300]:h[200,500]
+ * - :h[200,500]:w[100, 300]
+ *
+ * @param {string} query - The query string to be checked.
+ * @returns {boolean} Returns `true` if the query is a valid custom media query, otherwise `false`.
+ * @example
+ *
+ * isMediaQuery(':w[200]') // true
+ * isMediaQuery(':w100]')  // false
+ */
+export const isMediaQuery = (query: string): boolean => {
+    const regex = /^(?:(:w\[\d*(?:,\s?\d+)?])?(:h\[\d*(?:,\s?\d+)?])?|(:h\[\d*(?:,\s?\d+)?])?(:w\[\d*(?:,\s?\d+)?])?)$/
+
+    return query.length > 0 && regex.test(query)
+}
+
+/**
+ * Retrieves the first matching custom media query key based on the provided screen size.
+ *
+ * The function processes an array of media queries and returns the first query that matches
+ * the given screen size. The media queries can be in formats like:
+ * - w[200]
+ * - w[0, 200]
+ * - w[, 300]
+ * - h[200]
+ * - h[0, 500]
+ * - h[,200]
+ * - w[100, 300]:h[200,500]
+ * - h[200,500]:w[100, 300]
+ *
+ * @param {Array<[string, string | number]>} mediaQueries - An array of tuples containing media query keys and associated values.
+ * @param {ScreenSize} screenSize - An object representing the screen size to be checked against the media queries.
+ * @returns {string | undefined} Returns the first matching media query key or `undefined` if no match is found.
+ * @example
+ *
+ * const queries = [[':w[200]', 'value1'], [':h[300,500]', 'value2']]
+ * const size = { width: 250, height: 400 }
+ * getKeyForCustomMediaQuery(queries, size) // ':w[200]
+ */
+export const getKeyForCustomMediaQuery = (mediaQueries: Array<[string, string | number | undefined]>, screenSize: ScreenSize): string | undefined => {
+    const [matchedQuery] = mediaQueries
+        .flatMap(([key]) => {
+            if (key.includes('w') && key.includes('h')) {
+                return isWithinBreakpoint(key, screenSize) ? key : undefined
+            }
+
+            return key
+                .split(':')
+                .filter(Boolean)
+                .map(query => isWithinBreakpoint(query, screenSize) ? key : undefined)
+        })
+        .filter(Boolean)
+
+    return matchedQuery
+}

package/src/utils/styles.ts

@@ -0,0 +1,95 @@
+import type { CustomNamedStyles, ScreenSize } from '../types'
+import { getValueForBreakpoint } from './breakpoints'
+
+/**
+ * Proxies a function to parse its return value for custom media queries or breakpoints.
+ *
+ * If the function's string representation contains a custom media query or a defined breakpoint,
+ * the returned function will be proxied to parse its return value based on the provided screen size and breakpoints.
+ * If neither is found, the original function is returned.
+ *
+ * @template B - An object type where keys represent breakpoint names and values represent breakpoint values.
+ *
+ * @param {Function} fn - The function to be proxified.
+ * @param {keyof B & string} breakpoint - The breakpoint name to check against.
+ * @param {ScreenSize} screenSize - An object representing the screen size to be checked against the media queries.
+ * @param {B} breakpoints - An object representing the defined breakpoints.
+ *
+ * @returns {Function} Returns the proxified function or the original function if no custom media query or breakpoint is found in its string representation.
+ *
+ * @example
+ *
+ * const myFunction = () => ({ ':w[200]': 'value1', sm: 'value2' })
+ * const screenSize = { width: 250, height: 400 }
+ * const breakpoints = { sm: 300, md: 600 }
+ *
+ * const proxifiedFunction = proxifyFunction(myFunction, 'sm', screenSize, breakpoints)
+ * proxifiedFunction() // parsed style based on screenSize and breakpoints
+ */
+export const proxifyFunction = <B extends Record<string, number>>(
+    fn: Function, breakpoint: keyof B & string,
+    screenSize: ScreenSize,
+    breakpoints: B
+): Function => {
+    const stringifiedFunction = fn.toString()
+    const hasCustomMediaQuery = stringifiedFunction.includes(':w[') || stringifiedFunction.includes(':h[')
+    const hasBreakpoint = Object
+        .keys(breakpoints)
+        .some(bp => stringifiedFunction.includes(bp))
+
+    if (!hasCustomMediaQuery && !hasBreakpoint) {
+        return fn
+    }
+
+    return new Proxy(fn, {
+        apply: (target, thisArg, argumentsList) =>
+            parseStyle(target.apply(thisArg, argumentsList), breakpoint, screenSize, breakpoints)
+    })
+}
+
+/**
+ * Parses a style object to resolve custom media queries or breakpoints based on the provided screen size and breakpoints.
+ *
+ * The function processes each key-value pair in the style object. If the value is a function or a valid style (not an object or a 'transform' key),
+ * it is returned as-is. Otherwise, the function attempts to resolve the value based on the provided breakpoint, screen size, and defined breakpoints.
+ *
+ * @template T - The type of the style object.
+ * @template B - An object type where keys represent breakpoint names and values represent breakpoint values.
+ *
+ * @param {CustomNamedStyles<T, B>} style - The style object to be parsed.
+ * @param {keyof B & string} breakpoint - The breakpoint name to check against.
+ * @param {ScreenSize} screenSize - An object representing the screen size to be checked against the media queries.
+ * @param {B} breakpoints - An object representing the defined breakpoints.
+ *
+ * @returns {Record<string, string | number | Function>} Returns the parsed style object with resolved custom media queries or breakpoints.
+ *
+ * @example
+ *
+ * const style = { fontSize: { sm: '12px', md: '16px' } }
+ * const screenSize = { width: 300, height: 400 }
+ * const breakpoints = { xs: 0, sm: 300, md: 600 }
+ *
+ * const parsedStyle = parseStyle(style, 'sm', screenSize, breakpoints)
+ * // { fontSize: '12px' }
+ */
+export const parseStyle = <T, B extends Record<string, number>>(
+    style: CustomNamedStyles<T, B>,
+    breakpoint: keyof B & string,
+    screenSize: ScreenSize,
+    breakpoints: B
+) => Object
+    .fromEntries(Object
+        .entries(style)
+        .map(([key, value]) => {
+            const isDynamicFunction = typeof value === 'function'
+            const isValidStyle = typeof value !== 'object' || key === 'transform'
+
+            if (isDynamicFunction || isValidStyle) {
+                return [key, value]
+            }
+
+            const valueWithBreakpoint = value as Record<keyof B & string, string | number>
+
+            return [key, getValueForBreakpoint<B>(valueWithBreakpoint, breakpoint, screenSize, breakpoints)]
+        })
+    )