@lumx/core 3.21.2-alpha.1 → 3.21.2-alpha.3

package/js/constants/className/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Visually hidden a11y utility class name
+ */
+export declare const VISUALLY_HIDDEN = "visually-hidden";

package/js/constants/className/index.js

@@ -0,0 +1,6 @@
+/**
+ * Visually hidden a11y utility class name
+ */
+const VISUALLY_HIDDEN = 'visually-hidden';
+
+export { VISUALLY_HIDDEN };

package/js/constants/index.d.ts

@@ -1,3 +1,4 @@
 export * from './keycodes';
 export * from './components';
 export * from './enums';
+export * from './className';

package/js/constants/index.js

@@ -1,3 +1,4 @@
 export { BACKSPACE_KEY_CODE, DOWN_KEY_CODE, ENTER_KEY_CODE, ESCAPE_KEY_CODE, LEFT_KEY_CODE, RIGHT_KEY_CODE, SPACE_KEY_CODE, TAB_KEY_CODE, UP_KEY_CODE } from './keycodes/index.js';
 export { DIALOG_TRANSITION_DURATION, EXPANSION_PANEL_TRANSITION_DURATION, NOTIFICATION_TRANSITION_DURATION, SLIDESHOW_TRANSITION_DURATION, TOOLTIP_HOVER_DELAY, TOOLTIP_LONG_PRESS_DELAY } from './components/index.js';
 export { Alignment, AspectRatio, ColorPalette, ColorVariant, Emphasis, Kind, Orientation, Size, Theme, Typography, TypographyCustom, TypographyInterface, TypographyTitleCustom, WhiteSpace } from './enums/index.js';
+export { VISUALLY_HIDDEN } from './className/index.js';

package/js/types/Direction.d.ts

@@ -0,0 +1 @@
+export type Direction = 'top' | 'right' | 'bottom' | 'left' | 'vertical' | 'horizontal' | 'all';

package/js/types/Spacing.d.ts

@@ -0,0 +1 @@
+export type Spacing = 'margin' | 'padding';

package/js/types/index.d.ts

@@ -6,9 +6,12 @@ export type { HasCloseMode } from './HasCloseMode';
 export type { HasTheme } from './HasTheme';
 export type { GenericProps } from './GenericProps';
 export type { HeadingElement } from './HeadingElement';
+export type { KebabCase } from './KebabCase';
 export type { Point } from './Point';
 export type { Predicate } from './Predicate';
 export type { RectSize } from './RectSize';
 export type { TextElement } from './TextElement';
 export type { ValueOf } from './ValueOf';
 export type { LumxClassName } from './LumxClassName';
+export type { Direction } from './Direction';
+export type { Spacing } from './Spacing';

package/js/utils/_internal/color/index.d.ts

@@ -0,0 +1 @@
+export { resolveColorWithVariants } from './resolveColorWithVariants';

package/js/utils/_internal/color/resolveColorWithVariants.d.ts

@@ -0,0 +1,3 @@
+import type { ColorPalette, ColorVariant, ColorWithVariants } from '@lumx/core/js/constants';
+/** Resolve color & color variant from a `ColorWithVariants` and optionally a `ColorVariant`. */
+export declare function resolveColorWithVariants(colorWithVariants?: ColorWithVariants, colorVariant?: ColorVariant): [color?: ColorPalette, colorVariant?: ColorVariant];

package/js/utils/classNames/bem/block.d.ts

@@ -0,0 +1,18 @@
+import type { ClassValue } from 'classnames/types';
+import { type Modifier } from './generateBEMClass';
+/**
+ * Creates a BEM block class generator function for the given base class.
+ * Returns a function that generates BEM class names with optional modifiers.
+ *
+ * @param baseClass - The base BEM block class name (e.g., 'button', 'card')
+ * @returns A function that accepts:
+ *   - modifier - Optional BEM modifier (string, object, or array)
+ *   - additionalClasses - Optional additional classes to include
+ *
+ * @example
+ * const button = block('my-button');
+ * button(); // 'my-button'
+ * button('primary'); // 'my-button my-button--primary'
+ * button({ active: true }); // 'my-button my-button--active'
+ */
+export declare const block: (baseClass: string) => (modifier?: Modifier, additionalClasses?: ClassValue | ClassValue[]) => string;

package/js/utils/classNames/bem/block.js

@@ -0,0 +1,20 @@
+import { generateBEMClass } from './generateBEMClass.js';
+
+/**
+ * Creates a BEM block class generator function for the given base class.
+ * Returns a function that generates BEM class names with optional modifiers.
+ *
+ * @param baseClass - The base BEM block class name (e.g., 'button', 'card')
+ * @returns A function that accepts:
+ *   - modifier - Optional BEM modifier (string, object, or array)
+ *   - additionalClasses - Optional additional classes to include
+ *
+ * @example
+ * const button = block('my-button');
+ * button(); // 'my-button'
+ * button('primary'); // 'my-button my-button--primary'
+ * button({ active: true }); // 'my-button my-button--active'
+ */
+const block = (baseClass) => (modifier, additionalClasses) => generateBEMClass(baseClass, modifier, additionalClasses);
+
+export { block };

package/js/utils/classNames/bem/element.d.ts

@@ -0,0 +1,19 @@
+import type { ClassValue } from 'classnames/types';
+import { type Modifier } from './generateBEMClass';
+/**
+ * Creates a BEM element class generator function for the given base class.
+ * Returns a function that generates BEM element class names with optional modifiers.
+ *
+ * @param baseClass - The base BEM block class name (e.g., 'button', 'card')
+ * @returns A function that accepts:
+ *   - elem - The BEM element name (e.g., 'icon', 'title')
+ *   - modifier - Optional BEM modifier (string, object, or array)
+ *   - additionalClasses - Optional additional classes to include
+ *
+ * @example
+ * const button = element('my-button');
+ * button('icon'); // 'my-button__icon'
+ * button('icon', 'large'); // 'my-button__icon my-button__icon--large'
+ * button('icon', { active: true }); // 'my-button__icon my-button__icon--active'
+ */
+export declare const element: (baseClass: string) => (elem: string, modifier?: Modifier, additionalClasses?: ClassValue | ClassValue[]) => string;

package/js/utils/classNames/bem/element.js

@@ -0,0 +1,21 @@
+import { generateBEMClass } from './generateBEMClass.js';
+
+/**
+ * Creates a BEM element class generator function for the given base class.
+ * Returns a function that generates BEM element class names with optional modifiers.
+ *
+ * @param baseClass - The base BEM block class name (e.g., 'button', 'card')
+ * @returns A function that accepts:
+ *   - elem - The BEM element name (e.g., 'icon', 'title')
+ *   - modifier - Optional BEM modifier (string, object, or array)
+ *   - additionalClasses - Optional additional classes to include
+ *
+ * @example
+ * const button = element('my-button');
+ * button('icon'); // 'my-button__icon'
+ * button('icon', 'large'); // 'my-button__icon my-button__icon--large'
+ * button('icon', { active: true }); // 'my-button__icon my-button__icon--active'
+ */
+const element = (baseClass) => (elem, modifier, additionalClasses) => generateBEMClass(`${baseClass}__${elem}`, modifier, additionalClasses);
+
+export { element };

package/js/utils/classNames/bem/generateBEMClass.d.ts

@@ -0,0 +1,27 @@
+import type { ClassValue } from 'classnames/types';
+/**
+ * Modifier
+ * @example 'is-disabled'
+ * @example { 'is-disabled': true, 'is-selected': false }
+ * @example ['another-class'] // => Added as-is, not as a BEM modifier suffix
+ */
+export type Modifier = string | Record<string, boolean | undefined | null> | ClassValue[];
+/**
+ * Generates a BEM (Block Element Modifier) class name string.
+ * Combines a base class with optional modifiers and additional classes.
+ *
+ * @param baseClass - The base BEM class (block or element)
+ * @param modifier - Optional modifier as:
+ *   - string: creates `baseClass--modifier`
+ *   - object: creates `baseClass--key` for each truthy value
+ *   - array: passes through as additional classes
+ * @param additionalClasses - Optional additional classes to include
+ * @returns Combined class name string
+ *
+ * @example
+ * generateBEMClass('button'); // 'button'
+ * generateBEMClass('button', 'primary'); // 'button button--primary'
+ * generateBEMClass('button', { active: true, disabled: false }); // 'button button--active'
+ * generateBEMClass('button', 'primary', 'my-class'); // 'button button--primary my-class'
+ */
+export declare function generateBEMClass(baseClass: string, modifier?: Modifier, additionalClasses?: ClassValue | ClassValue[]): string;

package/js/utils/classNames/bem/generateBEMClass.js

@@ -0,0 +1,48 @@
+import classnames from 'classnames';
+
+function generateModifierClasses(baseClass, modifier) {
+    if (!modifier) {
+        return undefined;
+    }
+    if (Array.isArray(modifier)) {
+        return modifier;
+    }
+    if (typeof modifier === 'string') {
+        return `${baseClass}--${modifier}`;
+    }
+    const classes = [];
+    for (const [key, value] of Object.entries(modifier)) {
+        if (value)
+            classes.push(`${baseClass}--${key}`);
+    }
+    return classes;
+}
+/**
+ * Generates a BEM (Block Element Modifier) class name string.
+ * Combines a base class with optional modifiers and additional classes.
+ *
+ * @param baseClass - The base BEM class (block or element)
+ * @param modifier - Optional modifier as:
+ *   - string: creates `baseClass--modifier`
+ *   - object: creates `baseClass--key` for each truthy value
+ *   - array: passes through as additional classes
+ * @param additionalClasses - Optional additional classes to include
+ * @returns Combined class name string
+ *
+ * @example
+ * generateBEMClass('button'); // 'button'
+ * generateBEMClass('button', 'primary'); // 'button button--primary'
+ * generateBEMClass('button', { active: true, disabled: false }); // 'button button--active'
+ * generateBEMClass('button', 'primary', 'my-class'); // 'button button--primary my-class'
+ */
+function generateBEMClass(baseClass, modifier, additionalClasses) {
+    return classnames(
+    // Base class
+    baseClass, 
+    // Modifier(s)
+    generateModifierClasses(baseClass, modifier), 
+    // Additional classes
+    additionalClasses);
+}
+
+export { generateBEMClass };

package/js/utils/classNames/bem/index.d.ts

@@ -0,0 +1,2 @@
+export { block } from './block';
+export { element } from './element';

package/js/utils/classNames/bem/index.js

@@ -0,0 +1,2 @@
+export { block } from './block.js';
+export { element } from './element.js';

package/js/utils/classNames/color/index.d.ts

@@ -0,0 +1,43 @@
+import { ColorVariant, ColorWithVariants } from '@lumx/core/js/constants';
+/**
+ * Generates a Lumx color class name for the given type, color and variant.
+ * This is the base function used by font() and background() utilities.
+ *
+ * @param type - The color class type ('font' or 'background')
+ * @param propColor - The color palette name (e.g., 'primary', 'dark') with optional variant suffix (e.g., 'primary-L2')
+ * @param propColorVariant - Optional color variant override (e.g., 'L1', 'L2', 'D1', 'N')
+ * @returns The Lumx color class name or undefined if no color is provided
+ *
+ * @example
+ * color('font', 'dark', 'L2'); // 'lumx-color-font-dark-L2'
+ * color('background', 'primary'); // 'lumx-color-background-primary-N'
+ * color('font', 'primary-L2'); // 'lumx-color-font-primary-L2'
+ * color('font', undefined); // undefined
+ */
+export declare function color(type: 'font' | 'background', propColor: ColorWithVariants, propColorVariant?: ColorVariant): string;
+/**
+ * Generates a Lumx background color class name for the given color and variant.
+ *
+ * @param propColor - The color palette name (e.g., 'primary', 'dark', 'light')
+ * @param propColorVariant - The color variant (e.g., 'L1', 'L2', 'D1', 'N')
+ * @returns The Lumx background color class name
+ *
+ * @example
+ * background('dark', 'L2'); // 'lumx-color-background-dark-L2'
+ * background('primary', 'N'); // 'lumx-color-background-primary-N'
+ */
+export declare const background: (propColor: ColorWithVariants, propColorVariant?: ColorVariant) => string;
+/**
+ * Generates a Lumx font color class name for the given color and variant.
+ *
+ * @param propColor - The color palette name (e.g., 'primary', 'dark') with optional variant suffix (e.g., 'primary-L2')
+ * @param propColorVariant - Optional color variant override (e.g., 'L1', 'L2', 'D1', 'N')
+ * @returns The Lumx font color class name or undefined if no color is provided
+ *
+ * @example
+ * font('dark', 'L2'); // 'lumx-color-font-dark-L2'
+ * font('primary-L2'); // 'lumx-color-font-primary-L2'
+ * font('primary'); // 'lumx-color-font-primary-N'
+ * font(undefined); // undefined
+ */
+export declare const font: (propColor: ColorWithVariants, propColorVariant?: ColorVariant) => string;

package/js/utils/classNames/color/index.js

@@ -0,0 +1,50 @@
+import { ColorVariant } from '../../../constants/enums/index.js';
+import { resolveColorWithVariants } from '../../../../_internal/DPnPEC08.js';
+
+/**
+ * Generates a Lumx color class name for the given type, color and variant.
+ * This is the base function used by font() and background() utilities.
+ *
+ * @param type - The color class type ('font' or 'background')
+ * @param propColor - The color palette name (e.g., 'primary', 'dark') with optional variant suffix (e.g., 'primary-L2')
+ * @param propColorVariant - Optional color variant override (e.g., 'L1', 'L2', 'D1', 'N')
+ * @returns The Lumx color class name or undefined if no color is provided
+ *
+ * @example
+ * color('font', 'dark', 'L2'); // 'lumx-color-font-dark-L2'
+ * color('background', 'primary'); // 'lumx-color-background-primary-N'
+ * color('font', 'primary-L2'); // 'lumx-color-font-primary-L2'
+ * color('font', undefined); // undefined
+ */
+function color(type, propColor, propColorVariant) {
+    const [cColor, cColorVariant = ColorVariant.N] = resolveColorWithVariants(propColor, propColorVariant);
+    return `lumx-color-${type}-${cColor}-${cColorVariant}`;
+}
+/**
+ * Generates a Lumx background color class name for the given color and variant.
+ *
+ * @param propColor - The color palette name (e.g., 'primary', 'dark', 'light')
+ * @param propColorVariant - The color variant (e.g., 'L1', 'L2', 'D1', 'N')
+ * @returns The Lumx background color class name
+ *
+ * @example
+ * background('dark', 'L2'); // 'lumx-color-background-dark-L2'
+ * background('primary', 'N'); // 'lumx-color-background-primary-N'
+ */
+const background = (propColor, propColorVariant) => color('background', propColor, propColorVariant);
+/**
+ * Generates a Lumx font color class name for the given color and variant.
+ *
+ * @param propColor - The color palette name (e.g., 'primary', 'dark') with optional variant suffix (e.g., 'primary-L2')
+ * @param propColorVariant - Optional color variant override (e.g., 'L1', 'L2', 'D1', 'N')
+ * @returns The Lumx font color class name or undefined if no color is provided
+ *
+ * @example
+ * font('dark', 'L2'); // 'lumx-color-font-dark-L2'
+ * font('primary-L2'); // 'lumx-color-font-primary-L2'
+ * font('primary'); // 'lumx-color-font-primary-N'
+ * font(undefined); // undefined
+ */
+const font = (propColor, propColorVariant) => color('font', propColor, propColorVariant);
+
+export { background, color, font };

package/js/utils/classNames/index.d.ts

@@ -0,0 +1,6 @@
+export { default as join } from 'classnames';
+export * from './color';
+export * from './typography';
+export * from './spacing';
+export * from './visually-hidden';
+export * as bem from './bem';

package/js/utils/classNames/index.js

@@ -0,0 +1,7 @@
+export { default as join } from 'classnames';
+export { background, color, font } from './color/index.js';
+export { typography } from './typography/index.js';
+export { margin, margins, padding, paddings, spacing, spacings } from './spacing/index.js';
+export { visuallyHidden } from './visually-hidden/index.js';
+import * as index from './bem/index.js';
+export { index as bem };

package/js/utils/classNames/spacing/index.d.ts

@@ -0,0 +1,70 @@
+import type { Direction, Spacing } from '@lumx/core/js/types';
+import type { Size } from '@lumx/core/js/constants';
+/**
+ * Returns a lumx classname for the given type, direction and size. For example, for
+ * arguments type='padding', direction='right', size='regular' it returns lumx-spacing-padding-right-regular
+ * @param type - margin or padding
+ * @param direction - Direction
+ * @param size - Size
+ * @returns string
+ */
+export declare function spacing(type: Spacing, direction?: Direction, size?: Size | null): string;
+/**
+ * Returns a list of lumx classnames for the given types, directions and sizes. For example, for
+ * arguments [
+ *  { type: 'padding', direction: 'right', size: 'regular'},
+ *  { type: 'margin', direction: 'left', size: 'big'},
+ * ]
+ * it returns lumx-spacing-padding-right-regular lumx-spacing-margin-left-big
+ * @param spacingConfigs - Array of spacing configurations with direction and size
+ * @returns string
+ */
+export declare const spacings: (spacingConfigs: {
+    type: Spacing;
+    direction?: Direction;
+    size?: Size | null;
+}[]) => string;
+/**
+ * Returns a lumx margin classname for the given direction and size. For example, for
+ * arguments direction='right', size='regular' it returns lumx-spacing-margin-right-regular
+ * @param direction - Direction
+ * @param size - Size
+ * @returns string
+ */
+export declare const margin: (direction?: Direction, size?: Size | null) => string;
+/**
+ * Returns a list of lumx margin classnames for the given directions and sizes. For example, for
+ * arguments [
+ *  { direction: 'right', size: 'regular'},
+ *  { direction: 'left', size: 'big'},
+ * ]
+ * it returns lumx-spacing-margin-right-regular lumx-spacing-margin-left-big
+ * @param marginConfigs - Array of padding configurations with direction and size
+ * @returns string
+ */
+export declare const margins: (marginConfigs: {
+    direction?: Direction;
+    size?: Size | null;
+}[]) => string;
+/**
+ * Returns a lumx padding classname for the given direction and size. For example, for
+ * arguments direction='right', size='regular' it returns lumx-spacing-padding-right-regular
+ * @param direction - Direction
+ * @param size - Size
+ * @returns string
+ */
+export declare const padding: (direction?: Direction, size?: Size | null) => string;
+/**
+ * Returns a list of lumx padding classnames for the given directions and sizes. For example, for
+ * arguments [
+ *  { direction: 'right', size: 'regular'},
+ *  { direction: 'left', size: 'big'},
+ * ]
+ * it returns lumx-spacing-padding-right-regular lumx-spacing-padding-left-big
+ * @param paddingConfigs - Array of padding configurations with direction and size
+ * @returns Combined padding classnames as a string
+ */
+export declare const paddings: (paddingConfigs: {
+    direction?: Direction;
+    size?: Size | null;
+}[]) => string;

package/js/utils/classNames/spacing/index.js

@@ -0,0 +1,74 @@
+import classnames from 'classnames';
+
+/**
+ * Returns a lumx classname for the given type, direction and size. For example, for
+ * arguments type='padding', direction='right', size='regular' it returns lumx-spacing-padding-right-regular
+ * @param type - margin or padding
+ * @param direction - Direction
+ * @param size - Size
+ * @returns string
+ */
+function spacing(type, direction, size) {
+    let baseClass = `lumx-spacing-${type}`;
+    if (direction && direction !== 'all') {
+        baseClass = `${baseClass}-${direction}`;
+    }
+    if (size) {
+        baseClass = `${baseClass}-${size}`;
+    }
+    else if (size === null) {
+        baseClass = `${baseClass}-none`;
+    }
+    return baseClass;
+}
+/**
+ * Returns a list of lumx classnames for the given types, directions and sizes. For example, for
+ * arguments [
+ *  { type: 'padding', direction: 'right', size: 'regular'},
+ *  { type: 'margin', direction: 'left', size: 'big'},
+ * ]
+ * it returns lumx-spacing-padding-right-regular lumx-spacing-margin-left-big
+ * @param spacingConfigs - Array of spacing configurations with direction and size
+ * @returns string
+ */
+const spacings = (spacingConfigs) => classnames(spacingConfigs.map((spa) => spacing(spa.type, spa.direction, spa.size)));
+/**
+ * Returns a lumx margin classname for the given direction and size. For example, for
+ * arguments direction='right', size='regular' it returns lumx-spacing-margin-right-regular
+ * @param direction - Direction
+ * @param size - Size
+ * @returns string
+ */
+const margin = (direction, size) => spacing('margin', direction, size);
+/**
+ * Returns a list of lumx margin classnames for the given directions and sizes. For example, for
+ * arguments [
+ *  { direction: 'right', size: 'regular'},
+ *  { direction: 'left', size: 'big'},
+ * ]
+ * it returns lumx-spacing-margin-right-regular lumx-spacing-margin-left-big
+ * @param marginConfigs - Array of padding configurations with direction and size
+ * @returns string
+ */
+const margins = (marginConfigs) => spacings(marginConfigs.map(({ direction, size }) => ({ type: 'margin', direction, size })));
+/**
+ * Returns a lumx padding classname for the given direction and size. For example, for
+ * arguments direction='right', size='regular' it returns lumx-spacing-padding-right-regular
+ * @param direction - Direction
+ * @param size - Size
+ * @returns string
+ */
+const padding = (direction, size) => spacing('padding', direction, size);
+/**
+ * Returns a list of lumx padding classnames for the given directions and sizes. For example, for
+ * arguments [
+ *  { direction: 'right', size: 'regular'},
+ *  { direction: 'left', size: 'big'},
+ * ]
+ * it returns lumx-spacing-padding-right-regular lumx-spacing-padding-left-big
+ * @param paddingConfigs - Array of padding configurations with direction and size
+ * @returns Combined padding classnames as a string
+ */
+const paddings = (paddingConfigs) => spacings(paddingConfigs.map(({ direction, size }) => ({ type: 'padding', direction, size })));
+
+export { margin, margins, padding, paddings, spacing, spacings };

package/js/utils/classNames/typography/index.d.ts

@@ -0,0 +1,6 @@
+import type { Typography } from '@lumx/core/js/constants';
+/**
+ * Returns the classname associated to the given typography. For example, for Typography.title it returns
+ * lumx-typography-title
+ */
+export declare function typography(typo: Typography): string;

package/js/utils/classNames/typography/index.js

@@ -0,0 +1,9 @@
+/**
+ * Returns the classname associated to the given typography. For example, for Typography.title it returns
+ * lumx-typography-title
+ */
+function typography(typo) {
+    return `lumx-typography-${typo}`;
+}
+
+export { typography };

package/js/utils/classNames/visually-hidden/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Visually hidden class name.
+ * Used to hide elements from view but keep them readable from screen readers
+ */
+export declare const visuallyHidden: () => string;

package/js/utils/classNames/visually-hidden/index.js

@@ -0,0 +1,10 @@
+import '../../../constants/enums/index.js';
+import { VISUALLY_HIDDEN } from '../../../constants/className/index.js';
+
+/**
+ * Visually hidden class name.
+ * Used to hide elements from view but keep them readable from screen readers
+ */
+const visuallyHidden = () => VISUALLY_HIDDEN;
+
+export { visuallyHidden };

package/js/utils/index.d.ts

@@ -1 +1,2 @@
+export * as classNames from './classNames';
 export * from './events';

package/js/utils/index.js

@@ -1,2 +1,4 @@
+import * as index from './classNames/index.js';
+export { index as classNames };
 export { onButtonPressed, onEnterPressed, onEscapePressed } from './events/keyboard.js';
 export { detectHorizontalSwipe } from './events/swipe.js';

package/package.json

@@ -35,7 +35,7 @@
         "update-version-changelog": "yarn version-changelog ../../CHANGELOG.md"
     },
     "sideEffects": false,
-    "version": "3.21.2-alpha.1",
+    "version": "3.21.2-alpha.3",
     "devDependencies": {
         "@rollup/plugin-typescript": "^12.3.0",
         "@types/react": "^17.0.2",