@enact/ui/resolution/index.d.ts

A collection of simplified unstyled cross-platform UI components for Enact

// Type definitions for ui/resolution

type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
type Merge<M, N> = Omit<M, Extract<keyof M, keyof N>> & N;

export interface ResolutionDecoratorConfig extends Object {
  /**
 * Attaches an event listener to the window to listen for resize events.
 * 
 * When enabled, the resolution classes will be automatically updated when the window
is resized or when screen rotation occurs (such as when a device changes from
landscape to portrait orientation).
 */
  dynamic?: boolean;
  /**
 * An array of objects containing declarations for screen types to add to the list of known
screen types.
 */
  screenTypes?: object[];
}
export interface ResolutionDecoratorProps {}
export function ResolutionDecorator<P>(
  config: ResolutionDecoratorConfig,
  Component: React.ComponentType<P> | string,
): React.ComponentType<P & ResolutionDecoratorProps>;

export function ResolutionDecorator<P>(
  Component: React.ComponentType<P> | string,
): React.ComponentType<P & ResolutionDecoratorProps>;

/**
 * Object that stores the pixel conversion factors to each keyed unit.
 */
export declare const unitToPixelFactors: object;
/**
 * Sets up screen resolution scaling capabilities by defining an array of all the screens
being used.
 * 
 * These should be listed in order from smallest to largest, according to
width.
 * 
 * The  `name` ,  `pxPerRem` ,  `width` , and  `aspectRatioName`  properties are required for
each screen type in the array. Setting  `base: true`  on a screen type marks it as the
default resolution, upon which everything else will be based.
 * 
 * Executing this method also initializes the rest of the resolution-independence code.
 * 
 * Example:
 * ```
import ri from 'enact/ui/resolution';

ri.defineScreenTypes([
	{name: 'vga',     pxPerRem: 8,  width: 640,  height: 480,  aspectRatioName: 'standard'},
	{name: 'xga',     pxPerRem: 16, width: 1024, height: 768,  aspectRatioName: 'standard'},
	{name: 'hd',      pxPerRem: 16, width: 1280, height: 720,  aspectRatioName: 'hdtv'},
	{name: 'uw-hd',   pxPerRem: 16, width: 1920, height: 804,  aspectRatioName: 'cinema'},
	{name: 'fhd',     pxPerRem: 24, width: 1920, height: 1080, aspectRatioName: 'hdtv', base: true},
	{name: 'uw-uxga', pxPerRem: 24, width: 2560, height: 1080, aspectRatioName: 'cinema'},
	{name: 'qhd',     pxPerRem: 32, width: 2560, height: 1440, aspectRatioName: 'hdtv'},
	{name: 'wqhd',    pxPerRem: 32, width: 3440, height: 1440, aspectRatioName: 'cinema'},
	{name: 'uhd',     pxPerRem: 48, width: 3840, height: 2160, aspectRatioName: 'hdtv'},
	{name: 'uhd2',    pxPerRem: 96, width: 7680, height: 4320, aspectRatioName: 'hdtv'}
]);
```
 */
export function defineScreenTypes(types: object[]): void;
/**
 * Fetches the name of the screen type that best matches the current screen size.
 * 
 * The best match is defined as the screen type that is the closest to the screen resolution without
going over. ("The Price is Right" style.)
 */
export function getScreenType(rez: object): string;
/**
 * Calculate the base rem font size.
 * 
 * This is how the magic happens. This accepts an optional  `screenType`  name. If one isn't provided,
the currently detected screen type is used. This uses the config option  `orientationHandling` ,
which when set to "scale" and the screen is in portrait orientation (such as after screen rotation), will dynamically calculate
what the base font size should be, if the width were proportionally scaled down to fit in the portrait space.
 * 
 * To use, put the following in your application code:
 * ```
import ri from '@enact/ui/resolution';

ri.config.orientationHandling = 'scale';
ri.init();
```
 
 * This configuration is particularly useful for applications that support screen rotation and need
to maintain consistent scaling when the device orientation changes from landscape to portrait or vice versa.
This has no effect if the screen is in landscape, or if  `orientationHandling`  is unset.
 */
export function calculateFontSize(type: string): string;
/**
 * Returns the CSS classes for the given  `type` .
 * 
 * This function generates CSS class names that can be used to style components based on
the current screen resolution, orientation, and aspect ratio. The returned classes are
particularly useful for responsive layouts and handling screen rotation scenarios.
 * 
 * The following CSS classes are returned:
 * *  Orientation class :  `enact-orientation-landscape`  or  `enact-orientation-portrait`
 * *  Applied based on the current screen orientation
 * *  Updates automatically when device rotation occurs (if dynamic mode is enabled)
 * *  Resolution class :  `enact-res-{screentype}`
 * *  Examples:  `enact-res-fhd` ,  `enact-res-uhd` ,  `enact-res-hd` ,  `enact-res-qhd`
 * *  Applied based on the matched screen type
 * *  Aspect ratio class :  `enact-aspect-ratio-{aspectRatioName}`
 * *  Examples:  `enact-aspect-ratio-hdtv` ,  `enact-aspect-ratio-cinema` ,  `enact-aspect-ratio-standard`
 * *  Applied based on the screen type's aspect ratio name
 * 
 * Example return value:  `'enact-orientation-landscape enact-res-fhd enact-aspect-ratio-hdtv'`
 */
export function getResolutionClasses(type: string): string;
/**
 * Returns the ratio of pixels per rem for the given  `type`  to the pixels per rem for the base type.
 */
export function getRiRatio(type: string): number;
/**
 * Returns the pixels per rem for the given  `type` .
 */
export function getUnitToPixelFactors(type: string): number;
/**
 * Calculates the aspect ratio of the specified screen type.
 *
 * If no screen type is provided, the current screen type is used.
 */
export function getAspectRatio(type: string): number;
/**
 * Returns the name of the aspect ratio for a specified screen type, or for the default
screen type if none is provided.
 */
export function getAspectRatioName(type: string): string;
/**
 * Takes a provided pixel value and performs a scaling operation based on the current
screen type.
 */
export function scale(px: number): number;
/**
 * Convert to various unit formats.
 * 
 * Useful for converting pixels to a resolution-independent
measurement method, like "rem". Other units are available if defined in the
   object.
 * 
 * Example:
 * ```
import ri from '@enact/ui/resolution';

// Do calculations and get back the desired CSS unit.
var frameWidth = 250,
    frameWithMarginInches = ri.unit( 10 + frameWidth + 10, 'in' ), // '2.8125in' == frameWithMarginInches
    frameWithMarginRems = ri.unit( 10 + frameWidth + 10, 'rem' ); // '22.5rem' == frameWithMarginRems
```
 */
export function unit(pixels: string | number, toUnit: string): string | void;
/**
 * Shorthand for when you know you need to scale some pixel value and have it converted to "rem" for
proper scaling.
 * 
 * This runs    and    together.
 */
export function scaleToRem(pixels: number): string | void;
/**
 * The default configurable options for   . Additional resolutions
may be added.
 */
export interface selectSrcOptions {
  /**
   * HD / 720p Resolution image asset source URI/URL
   */
  hd?: string; /**
   * FHD / 1080p Resolution image asset source URI/URL
   */
  fhd?: string; /**
   * UHD / 4K Resolution image asset source URI/URL
   */
  uhd?: string;
}
/**
 * Selects the ideal image asset from a set of assets, based on various screen
resolutions: HD (720p), FHD (1080p), UHD (4k).
 * 
 * When a  `src`  argument is provided,  `selectSrc()`  will choose the best image with
respect to the current screen resolution.  `src`  may be either the traditional
string, which will pass straight through, or a hash/object of screen types and
their asset sources (keys:screen and values:src). The image sources will be used
when the screen resolution is less than or equal to the provided screen types.
 * 
 * Example:
 * ```
// Take advantage of the multi-res mode
import {Image} from '@enact/ui/Image';

const src = {
    'hd': 'http://lorempixel.com/64/64/city/1/',
    'fhd': 'http://lorempixel.com/128/128/city/1/',
    'uhd': 'http://lorempixel.com/256/256/city/1/'
};
...
<Image src={src} ... />
...
```
 */
export function selectSrc(
  src: string | ui_resolution_selectSrcSrcOptions,
): string;
/**
 * This will need to be re-run any time the screen size changes, so all the values can be re-cached.
 */
export function init(args: object): void;
export interface LinearScalingConfig {
  /**
 * Enables linear scaling calculation for
font sizes and unit conversions. Default:  `true` .
 */
  active: boolean; /**
 * Determines the
reference screen used for linear scaling calculation.
Default:  `linearScalingType.currentScreen` .
 */
  type: ui_resolution_linearScalingType;
}
/**
 * Configuration options for resolution independence behavior.
 */
export interface ResolutionConfig {
  /**
 * Determines how to calculate
font-size. When set to  `'scale'`  and the screen is in landscape orientation,
calculates font-size linearly based on screen resolution. When set to  `'normal'` ,
the font-size will be the pxPerRem value of the best match screen type.
Default:  `'scale'`
 */
  fontSizeHandling: "normal" | "scale"; /**
 * Determines how to handle screen
orientation and rotation. When set to  `'scale'`  and the screen is in portrait
orientation (due to screen rotation), dynamically calculates the base font size
based on proportional scaling. When set to  `'normal'` , uses the standard pxPerRem
value. This is particularly useful for supporting device rotation scenarios.
Default:  `'normal'`
 */
  orientationHandling: "normal" | "scale"; /**
   * Configuration for linear scaling mode.
   */
  linearScaling: LinearScalingConfig;
}