@dnb/eufemia
Version:
DNB Eufemia Design System UI Library
111 lines (110 loc) • 5.26 kB
TypeScript
/**
* Space helper
*
*/
import type { CSSProperties } from 'react';
import { type ClassValue } from 'clsx';
import type { SpaceType, SpacingUnknownProps, SpacingProps, SpacePositiveSize, SpacePositiveRemValue, InnerSpaceType } from './types';
type SpaceNumber = number;
type InnerSpacingProps = Omit<SpacingProps, 'innerSpace'> & {
innerSpace?: InnerSpaceType;
};
export declare const spacingDefaultProps: SpacingProps;
export declare const spacePatterns: Record<SpacePositiveSize, SpacePositiveRemValue>;
export declare const calc: (...types: Array<SpaceType>) => any;
/**
* Creates a valid space CSS style out from given space types
*
* @param props
* @returns { '--padding-b-l': '2rem', '--padding-t-l': '1rem' }
*/
export declare const createSpacingProperties: (props: InnerSpacingProps) => CSSProperties;
/**
* Creates CSS custom properties for outer spacing (margin).
*
* Computes the resolved rem value for each direction and media size based on the
* `top`, `right`, `bottom`, `left` and `space` props and returns them
* as `--margin-{t|r|b|l}-{s|m|l}` custom properties, following the same
* pattern as innerSpace but with margin prefix. These properties are meant to later
* drive the margin via `var(--margin-*)` in CSS, while the existing
* `dnb-space__{direction}--{size}` classes still apply the actual margin for now.
*
* @param props
* @returns { '--margin-t-s': '1rem', '--margin-r-s': '0' }
*/
export declare const createMarginProperties: (props: SpacingProps | SpacingUnknownProps) => CSSProperties;
export type SpacingReturn = {
className: string[];
style: CSSProperties | undefined;
};
/**
* Combined helper that returns both CSS classes and CSS custom properties
* for spacing. Components should spread both into their root element.
*
* @example
* const spacing = createSpacing(props)
* className = clsx('dnb-my-component', ...spacing.className, className)
* style = { ...style, ...spacing.style }
*
* @param props - component props containing spacing properties
* (top, right, bottom, left, space, innerSpace, noCollapse)
* @param elementName - optional element name for inline detection
* @returns { className: string[], style: React.CSSProperties | undefined }
*/
export declare const createSpacing: (props: SpacingProps | SpacingUnknownProps, elementName?: string | null) => SpacingReturn;
export type ApplySpacingTarget = {
className?: ClassValue;
style?: CSSProperties;
} & Record<string, unknown>;
/**
* @deprecated Use `useSpacing` instead. This plain-function variant
* does not support `Space.ResponsiveContext` context.
*/
export declare const applySpacing: <T extends ApplySpacingTarget>(props: SpacingProps | SpacingUnknownProps, target: T, elementName?: string | null) => T;
/**
* React hook that applies spacing to a target props object.
*
* Works like `applySpacing` — appends spacing CSS classes to
* `className`, merges CSS custom properties into `style`, and strips
* spacing keys so the result can be spread onto a DOM element.
*
* Additionally reads `SpaceResponsiveContext` (provided by
* `Space.ResponsiveContext`) and, when the component is rendered inside that
* wrapper, appends a `dnb-space-responsive--<density>` CSS class.
* This lets descendant components opt into responsive spacing driven
* by `--responsive-spacing-*` custom properties.
*
* Must be called at the top level of a React component (hook rules).
*
* @example
* // Basic usage inside a component
* const mainParams = useSpacing(props, {
* ...attributes,
* className: clsx('dnb-button', className),
* })
*
* @example
* // Wrapping with Space.ResponsiveContext enables responsive spacing
* <Space.ResponsiveContext>
* <Button top="large">Click</Button>
* </Space.ResponsiveContext>
* // Button's root element will include 'dnb-space-responsive--basis'
*
* @param props - component props containing spacing properties
* (top, right, bottom, left, space, innerSpace, noCollapse)
* @param target - props object to merge spacing into
* @param elementName - optional element name for inline detection
* @returns a new object of the same shape as `target`, with spacing merged in
*/
export declare const useSpacing: <T extends ApplySpacingTarget>(props: SpacingProps | SpacingUnknownProps, target: T, elementName?: string | null) => T;
export declare const translateSpace: (type: SpaceType) => any;
export declare const splitTypes: (types: SpaceType | Array<SpaceType>) => SpaceType[] | (number | SpacePositiveSize)[];
export declare const sumTypes: (types: SpaceType | Array<SpaceType>) => any;
export declare const createTypeModifiers: (types: SpaceType) => Array<SpaceType>;
export declare const findType: (num: SpaceNumber) => SpaceType;
export declare const findTypeAll: (num: SpaceNumber) => Array<SpacePositiveSize | SpacePositiveRemValue>;
export declare const findNearestTypes: (num: SpaceNumber, multiply?: boolean) => any[];
export declare const isValidSpaceProp: (propName: string) => boolean;
export declare const removeSpaceProps: <Props extends SpacingProps>(props: Props) => Omit<Props, keyof SpacingProps>;
export declare const isInline: (elementName: string) => boolean;
export {};