@devseed-ui/theme-provider/dist/index.d.ts

devseed UI Kit Theme

import React from 'react';
import { DefaultTheme, ThemedCssFunction } from 'styled-components';

declare module '@devseed-ui/theme-provider' {
  /**
   * Creates a color palette based off of the provided base color including
   * lightened/darkened/transparent versions of that color.
   *
   * Uses a scale from 50 - 900 to indicate the color value. Values lower than 500
   * are lightened, above 500 are darkened and values ending with `a` have a alpha
   * channel.
   */
  function createColorPalette(
    name: string,
    baseColor: string,
  ): {
    [key: string]: string;
  };
}

interface ThemeColor {
  [key: string]: any;

  /**
   * Background color for filled elements that sit on top of the body.
   * (cards, panel, modal...)
   * @default #FFFFF
   */
  surface?: string;
  /**
   * Base color for the site. Text and all elements that are not colored.
   * @default #443F3F
   */
  base?: string;
  /**
   * Primary color.
   * @default #CF3F02
   */
  primary?: string;
  /**
   * Secondary color.
   * @default #E2C044
   */
  secondary?: string;
  /**
   * State color: danger
   * @default #A71D31
   */
  danger?: string;
  /**
   * State color: warning
   * @default #E2C044
   */
  warning?: string;
  /**
   * State color: success
   * @default #4DA167
   */
  success?: string;
  /**
   * State color: info
   * @default #2E86AB
   */
  info?: string;

  // Color palettes
  // For each color above a palette with darker/lighter colors is generated.

  /**
   * Only used for body background color. Uses surface if not provided.
   * @default $.color.surface
   */
  background?: string;
  /**
   * Color for links. Uses primary if not defined.
   * @default $.color.primary
   */
  link?: string;
}

interface ThemeTypeBase {
  [key: string]: any;

  /**
   * <@default $.type.base.family
   */
  family?: string;
  /**
   * @default $.type.base.style
   */
  style?: string;
  /**
   * @default $.type.base.settings
   */
  settings?: string;
  /**
   * @default $.type.base.case
   */
  case?: string;
  /**
   * @default $.type.base.light
   */
  light?: string;
  /**
   * @default $.type.base.regular
   */
  regular?: string;
  /**
   * @default $.type.base.medium
   */
  medium?: string;
  /**
   * @default $.type.base.bold
   */
  bold?: string;
  /**
   * @default $.type.base.bold
   */
  weight?: string;
  /**
   * @default none
   */
  textTransform?: string;
}

interface ThemeType {
  [key: string]: any;

  /**
   * Base type settings for the site.
   */
  base?: Omit<ThemeTypeBase, 'textTransform'> & {
    size?: string;
    /**
     * Uses 1.5 times the size when not provided
     * @default "$.color.base * 1.5"
     */
    leadSize?: string;
    line?: string;
    /**
     * Uses the base color when not provided.
     * @default $.color.base
     */
    color?: string;
    antialiasing?: number;
  };

  /**
   * Heading type definition. When not provided the same settings as base
   * type are used.
   */
  heading?: ThemeTypeBase;

  /**
   * Overline type definition. When not provided the same settings as base
   * type are used.
   */
  overline?: Omit<ThemeTypeBase, 'textTransform'> & {
    /**
     * @default uppercase
     */
    textTransform?: string;
  };
}

interface ThemeShape {
  [key: string]: any;

  /**
   * @default 0.25rem
   */
  rounded?: string;
  /**
   * @default 320rem
   */
  ellipsoid?: string;
}

interface ThemeLayout {
  [key: string]: any;

  /**
   * @default 1rem
   */
  space?: string;
  /**
   * @default 1px
   */
  border?: string;
  /**
   * @default 320px
   */
  min?: string;
  /**
   * @default 1280px
   */
  max?: string;
}

interface ThemeButton {
  [key: string]: any;

  /**
   * Button type definition. When not provided the same settings as base
   * type are used.
   */
  type?: {
    [key: string]: any;

    family?: string;
    style?: string;
    settings?: string;
    case?: string;
    weight?: string;
  };

  /**
   * Button shape definition. When not provided the same settings as shape
   * type are used.
   */
  shape?: {
    [key: string]: any;

    border?: string;
    rounded?: string;
  };
}

interface ThemeBoxShadow {
  [key: string]: any;

  /**
   * @default "inset 0px 0px 3px 0px {color base-50a}"
   */
  inset?: string;
  /**
   * @default "0 -1px 1px 0 {color base-100a}, 0 2px 6px 0 {color base-200a}"
   */
  input?: string;
  /**
   * @default "0 0 4px 0 {color base-100a}, 0 2px 2px 0 {color base-100a}"
   */
  elevationA?: string;
  /**
   * @default "0 0 4px 0 {color base-100a}, 0 4px 4px 0 {color base-100a}"
   */
  elevationB?: string;
  /**
   * @default "0 0 4px 0 {color base-100a}, 0 8px 12px 0 {color base-100a}"
   */
  elevationC?: string;
  /**
   * @default "0 0 4px 0 {color base-100a}, 0 12px 24px 0 {color base-100a}"
   */
  elevationD?: string;
}

interface ThemeMediaRanges {
  xsmall?: [null, number];
  small?: [number, number];
  medium?: [number, number];
  large?: [number, number];
  xlarge?: [number, null];
}

interface Theme {
  [key: string]: any;

  /**
   * Base theme colors. These will serve as base for all other elements, but
   * they can be overridden on an individual basis.
   */
  color?: ThemeColor;
  /**
   * Typography definition
   */
  type?: ThemeType;
  /**
   * Values for shapes.
   */
  shape?: ThemeShape;
  /**
   * Values for layout settings.
   */
  layout?: ThemeLayout;
  /**
   * Button specific settings.
   */
  button?: ThemeButton;
  /**
   * Box shadow definitions for different elevation effects.
   */
  boxShadow?: ThemeBoxShadow;
  /**
   * Ranges for media queries.
   * @default {ThemeMediaRanges} Each range spans 224px:
   *   xsmall = [null, 543],
   *   small = [544, 767],
   *   medium = [768, 991],
   *   large = [992, 1215],
   *   xlarge = [1216, null]
   */
  mediaRanges?: ThemeMediaRanges;
}

declare module '@devseed-ui/theme-provider' {
  export interface DevseedUIThemeColor extends ThemeColor {}
  export interface DevseedUIThemeType extends ThemeType {}
  export interface DevseedUIThemeShape extends ThemeShape {}
  export interface DevseedUIThemeLayout extends ThemeLayout {}
  export interface DevseedUIThemeButton extends ThemeButton {}
  export interface DevseedUIThemeBoxShadow extends ThemeBoxShadow {}
  export interface DevseedUIThemeMediaRanges extends ThemeMediaRanges {}
  export interface DevseedUITheme extends Theme {}
}

declare module 'styled-components' {
  export interface DefaultTheme extends Theme {}
}

declare module '@devseed-ui/theme-provider' {
  /**
   * Creates a UI theme by combining the provided options with the default ones.
   * When an override for a value is provided, it gets propagated to all the
   * variables that use that value. For example: The primary color will be used
   * for links unless a color for "link" is provided.
   *
   * @param {DefaultTheme} definition The theme definition
   *
   * @returns DefaultTheme
   */
  function createUITheme(definition: DefaultTheme): DefaultTheme;

  /**
   * Theme provider for the ui-library.
   * Supports a custom theme through a `theme` prop.
   */
  class DevseedUiThemeProvider extends React.Component<
    {
      theme?: DefaultTheme | ((mainTheme: DefaultTheme) => DefaultTheme);
    },
    any
  > {}

  const theme: {
    main: DefaultTheme;
  };
}

type StyledComponentsCSS$1 = () => any;

declare module '@devseed-ui/theme-provider' {
  /**
   * Applies anti-aliasing to font rendering, making the text more readable and
   * pleasing to the eye. Webkit and mozilla specific.
   */
  function antialiased(): StyledComponentsCSS$1;

  /**
   * Hides elements visually, but preserving its accessibility to screen readers
   * or crawlers. Useful for semantic solutions.
   */
  function visuallyHidden(): StyledComponentsCSS$1;

  /**
   * Removes default list (`ul` and `ol`) styling. Say goodbye to default
   * padding, margin, and bullets/numbers.
   */
  function listReset(): StyledComponentsCSS$1;

  /**
   * Truncates a text string and applies ellipsis. Requires a declared width
   * value.
   */
  function truncated(): StyledComponentsCSS$1;

  /**
   * Applies disabled styles to an element, and disabled pointer events.
   */
  function visuallyDisabled(): StyledComponentsCSS$1;

  /**
   * The same behavior as `disabled`, but the pointer events remain active. This
   * is useful when, for example, paired with a tooltip that needs the `hover`
   * event to fire.
   */
  function disabled(): StyledComponentsCSS$1;

  /**
   * Constrains element content to its declared height, preventing vertical
   * scrolling.
   */
  function unscrollableY(): StyledComponentsCSS$1;

  /**
   * Constrains element content to its declared width, preventing horizontal
   * scrolling.
   */
  function unscrollableX(): StyledComponentsCSS$1;
}

declare module '@devseed-ui/theme-provider' {
  /**
   * Creates a math function to add values. It takes into account
   * only the unit of the first value. Eg: 2rem + 2 = 4rem | 2 + 2rem = 4
   * This function is ready to work with styled-components so that any function
   * passed as an argument will receive the component props.
   *
   * @param {string} a First value
   * @param {string} b Second value
   */
  function add<T extends number | string>(a: T, b: number | string): T;

  /**
   * Creates a math function to subtract values. It takes into account
   * only the unit of the first value. Eg: 4rem - 2 = 2rem | 4 - 2rem = 2
   * This function is ready to work with styled-components so that any function
   * passed as an argument will receive the component props.
   *
   * @param {string} a First value
   * @param {string} b Second value
   */
  function subtract<T extends number | string>(a: T, b: number | string): T;

  /**
   * Creates a math function to divide values. It takes into account
   * only the unit of the first value. Eg: 4rem / 2 = 2rem | 4 / 2rem = 2
   * This function is ready to work with styled-components so that any function
   * passed as an argument will receive the component props.
   *
   * @param {string} a First value
   * @param {string} b Second value
   */
  function divide<T extends number | string>(a: T, b: number | string): T;

  /**
   * Creates a math function to multiply values. It takes into account
   * only the unit of the first value. Eg: 2rem * 2 = 4rem | 2 * 2rem = 4
   * This function is ready to work with styled-components so that any function
   * passed as an argument will receive the component props.
   *
   * @param {string} a First value
   * @param {string} b Second value
   */
  function multiply<T extends number | string>(a: T, b: number | string): T;

  /**
   * Creates a math function that returns the minimum of two values. Units are
   * discarded when doing the comparison, but the value is returned with a unit
   * if both arguments has the same one or if only one has it.
   * Eg: 10px, 3px => 3px
   * Eg: 10px, 3 => 3px
   * Eg: 1rem, 3px => 1
   *
   * This function is ready to work with styled-components
   * so that any function passed as an argument will receive the component props.
   *
   * @param {string} a First value
   * @param {string} b Second value
   */
  function min<T extends number | string>(a: T, b: number | string): T;

  /**
   * Creates a math function that returns the maximum of two values. Units are
   * discarded when doing the comparison, but the value is returned with a unit
   * if both arguments has the same one or if only one has it.
   * Eg: 10px, 3px => 10px
   * Eg: 10px, 3 => 10px
   * Eg: 1rem, 3px => 3
   *
   * This function is ready to work with styled-components
   * so that any function passed as an argument will receive the component props.
   *
   * @param {string} a First value
   * @param {string} b Second value
   */
  function max<T extends number | string>(a: T, b: number | string): T;
}

type StyledComponentsCSS = () => any;

declare module '@devseed-ui/theme-provider' {
  type ThemeValPath =
    | 'color.base'
    | 'color.surface'
    | 'color.primary'
    | 'color.secondary'
    | 'color.danger'
    | 'color.warning'
    | 'color.success'
    | 'color.info'
    | 'color.background'
    | 'color.link'
    | 'color.base-50'
    | 'color.base-50a'
    | 'color.base-100'
    | 'color.base-100a'
    | 'color.base-200'
    | 'color.base-200a'
    | 'color.base-300'
    | 'color.base-300a'
    | 'color.base-400'
    | 'color.base-400a'
    | 'color.base-500'
    | 'color.base-600'
    | 'color.base-700'
    | 'color.base-800'
    | 'color.base-900'
    | 'color.surface-50'
    | 'color.surface-50a'
    | 'color.surface-100'
    | 'color.surface-100a'
    | 'color.surface-200'
    | 'color.surface-200a'
    | 'color.surface-300'
    | 'color.surface-300a'
    | 'color.surface-400'
    | 'color.surface-400a'
    | 'color.surface-500'
    | 'color.surface-600'
    | 'color.surface-700'
    | 'color.surface-800'
    | 'color.surface-900'
    | 'color.primary-50'
    | 'color.primary-50a'
    | 'color.primary-100'
    | 'color.primary-100a'
    | 'color.primary-200'
    | 'color.primary-200a'
    | 'color.primary-300'
    | 'color.primary-300a'
    | 'color.primary-400'
    | 'color.primary-400a'
    | 'color.primary-500'
    | 'color.primary-600'
    | 'color.primary-700'
    | 'color.primary-800'
    | 'color.primary-900'
    | 'color.secondary-50'
    | 'color.secondary-50a'
    | 'color.secondary-100'
    | 'color.secondary-100a'
    | 'color.secondary-200'
    | 'color.secondary-200a'
    | 'color.secondary-300'
    | 'color.secondary-300a'
    | 'color.secondary-400'
    | 'color.secondary-400a'
    | 'color.secondary-500'
    | 'color.secondary-600'
    | 'color.secondary-700'
    | 'color.secondary-800'
    | 'color.secondary-900'
    | 'color.danger-50'
    | 'color.danger-50a'
    | 'color.danger-100'
    | 'color.danger-100a'
    | 'color.danger-200'
    | 'color.danger-200a'
    | 'color.danger-300'
    | 'color.danger-300a'
    | 'color.danger-400'
    | 'color.danger-400a'
    | 'color.danger-500'
    | 'color.danger-600'
    | 'color.danger-700'
    | 'color.danger-800'
    | 'color.danger-900'
    | 'color.warning-50'
    | 'color.warning-50a'
    | 'color.warning-100'
    | 'color.warning-100a'
    | 'color.warning-200'
    | 'color.warning-200a'
    | 'color.warning-300'
    | 'color.warning-300a'
    | 'color.warning-400'
    | 'color.warning-400a'
    | 'color.warning-500'
    | 'color.warning-600'
    | 'color.warning-700'
    | 'color.warning-800'
    | 'color.warning-900'
    | 'color.success-50'
    | 'color.success-50a'
    | 'color.success-100'
    | 'color.success-100a'
    | 'color.success-200'
    | 'color.success-200a'
    | 'color.success-300'
    | 'color.success-300a'
    | 'color.success-400'
    | 'color.success-400a'
    | 'color.success-500'
    | 'color.success-600'
    | 'color.success-700'
    | 'color.success-800'
    | 'color.success-900'
    | 'color.info-50'
    | 'color.info-50a'
    | 'color.info-100'
    | 'color.info-100a'
    | 'color.info-200'
    | 'color.info-200a'
    | 'color.info-300'
    | 'color.info-300a'
    | 'color.info-400'
    | 'color.info-400a'
    | 'color.info-500'
    | 'color.info-600'
    | 'color.info-700'
    | 'color.info-800'
    | 'color.info-900'
    | 'type.base.root'
    | 'type.base.size'
    | 'type.base.leadSize'
    | 'type.base.line'
    | 'type.base.color'
    | 'type.base.family'
    | 'type.base.style'
    | 'type.base.settings'
    | 'type.base.case'
    | 'type.base.light'
    | 'type.base.regular'
    | 'type.base.medium'
    | 'type.base.bold'
    | 'type.base.weight'
    | 'type.base.antialiasing'
    | 'type.heading.family'
    | 'type.heading.style'
    | 'type.heading.settings'
    | 'type.heading.case'
    | 'type.heading.light'
    | 'type.heading.regular'
    | 'type.heading.medium'
    | 'type.heading.bold'
    | 'type.heading.weight'
    | 'type.heading.textTransform'
    | 'type.overline.family'
    | 'type.overline.style'
    | 'type.overline.settings'
    | 'type.overline.case'
    | 'type.overline.light'
    | 'type.overline.regular'
    | 'type.overline.medium'
    | 'type.overline.bold'
    | 'type.overline.weight'
    | 'type.overline.textTransform'
    | 'shape.rounded'
    | 'shape.ellipsoid'
    | 'layout.space'
    | 'layout.border'
    | 'layout.min'
    | 'layout.max'
    | 'button.type.family'
    | 'button.type.style'
    | 'button.type.settings'
    | 'button.type.case'
    | 'button.type.weight'
    | 'button.shape.border'
    | 'button.shape.rounded'
    | 'boxShadow.inset'
    | 'boxShadow.input'
    | 'boxShadow.elevationA'
    | 'boxShadow.elevationB'
    | 'boxShadow.elevationC'
    | 'boxShadow.elevationD'
    | 'mediaRanges.xsmall'
    | 'mediaRanges.small'
    | 'mediaRanges.medium'
    | 'mediaRanges.large'
    | 'mediaRanges.xlarge';

  /**
   * Returns a function to be used with styled-components and gets a value from
   * the theme property.
   *
   * @param {string} path The path to get from theme
   */
  function themeVal(
    path: ThemeValPath,
  ): (props: { theme: { [key: string]: string | number } }) => string | number;

  /**
   * Allows a function to be used with style-components interpolation, passing the
   * component props to each one of the functions arguments if those arguments are
   * functions.
   *
   * Useful in conjunction with themeVal. Instead of:
   * ${(props) => rgba(props.theme.colors.primaryColor, 0.16)}
   * you can do
   * ${rgbaFn(themeVal('colors.primaryColor'), 0.16)}
   *
   * @param {function} fn The function to wrap.
   *
   * @returns {function} Curried function
   */
  function stylizeFunction(
    fn: (...args: Array<any>) => any,
  ): StyledComponentsCSS;

  /**
   * Returns the layout.space value form the theme multiplied by the
   * given multiplier.
   *
   * @param {number} m multiplier
   */
  function glsp(...multiplier: number[]): StyledComponentsCSS | string;

  /**
   * Polished rgba function but stylized.
   */
  function rgba(fn: (...args: Array<any>) => any): any;

  /**
   * Return a function that when executed appends the `unit` to the value.
   */
  function unitify(unit: string): (v: any) => any;

  /**
   * Return the given value with `rem` appended.
   * If value is a function will execute it. This allows to use directly in
   * styled-components with themeVal
   */
  function rem(v: any): any;

  /**
   * Return the given value with `px` appended.
   * If value is a function will execute it. This allows to use directly in
   * styled-components with themeVal
   */
  function px(v: any): any;

  /**
   * Convert the given value to pixels using the base size defined in the theme.
   * (theme.type.base.root)
   * If value is a function will execute it. This allows to use directly in
   * styled-components with themeVal
   */
  function val2px(v: any): any;

  /**
   * Convert the given value to rem using the base size defined in the theme.
   * (theme.type.base.root)
   * If value is a function will execute it. This allows to use directly in
   * styled-components with themeVal
   */
  function val2rem(v: any): any;
}

declare module '@devseed-ui/theme-provider' {
  /**
   * Styled-components helper to write code for the different media queries
   * breakpoints.
   */
  const media: {
    xsmallDown: ThemedCssFunction<DefaultTheme>;
    smallUp: ThemedCssFunction<DefaultTheme>;
    smallOnly: ThemedCssFunction<DefaultTheme>;
    smallDown: ThemedCssFunction<DefaultTheme>;
    mediumUp: ThemedCssFunction<DefaultTheme>;
    mediumOnly: ThemedCssFunction<DefaultTheme>;
    mediumDown: ThemedCssFunction<DefaultTheme>;
    largeUp: ThemedCssFunction<DefaultTheme>;
    largeOnly: ThemedCssFunction<DefaultTheme>;
    largeDown: ThemedCssFunction<DefaultTheme>;
    xlargeUp: ThemedCssFunction<DefaultTheme>;
  }
}