@lumx/core 4.2.0 → 4.2.1-alpha.1

package/js/types/NestedComponents.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A component reference that can be used in nested components.
+ * This is framework-agnostic and works with both React components (functions)
+ * and Vue components (objects/constructors).
+ */
+export type ComponentLike = any;
+/**
+ * Represents a mapping of nested component names to their component implementations.
+ * Used to provide component references to LumX core components that accept nested components.
+ *
+ * This type is framework-agnostic and can accept both React and Vue component types.
+ * While ComponentLike is typed as any, this structured type provides better documentation
+ * and a centralized location for future refinements.
+ *
+ * @example
+ * // React usage
+ * Flag(props, { Text });
+ *
+ * @example
+ * // Vue usage with VueToJSX
+ * const ui = VueToJSX(FlagUI, { nestedComponents: { Text } });
+ */
+export type NestedComponents = Record<string, ComponentLike>;

package/js/types/Selector.d.ts

@@ -0,0 +1,11 @@
+type FunctionSelector<TObject, TValue> = (o: TObject) => TValue;
+type FieldSelector<TObject, TValue> = keyof {
+    [TKey in keyof TObject as TObject[TKey] extends TValue ? TKey : never]: TObject[TKey];
+};
+/**
+ * Value selector on an object
+ * - either via an object key
+ * - or a selector function
+ */
+export type Selector<TObject, TValue = string> = FieldSelector<TObject, TValue> | FunctionSelector<TObject, TValue>;
+export {};

package/js/types/index.d.ts

@@ -15,9 +15,11 @@ export type { ValueOf } from './ValueOf';
 export type { LumxClassName } from './LumxClassName';
 export type { Direction } from './Direction';
 export type { Spacing } from './Spacing';
+export type { NestedComponents, ComponentLike } from './NestedComponents';
 export type { ObjectValues } from './ObjectValues';
 export type { HasRequiredLinkHref } from './HasRequiredLinkHref';
 export type { HasPolymorphicAs } from './HasPolymorphicAs';
 export type { CommonRef } from './CommonRef';
 export type { HasAriaDisabled } from './HasAriaDisabled';
 export type { AriaAttributes } from './AriaAttributes';
+export type { Selector } from './Selector';

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

@@ -0,0 +1,15 @@
+import { type Modifier } from './modifier';
+/**
+ * Generates a BEM block + modifier class name string.
+ * Combines a base class with optional modifiers and additional classes.
+ *
+ * @param baseName   The base BEM class
+ * @param modifier   Optional modifiers
+ * @returns Combined class name string
+ *
+ * @example
+ * block('button'); // 'button'
+ * block('button', { active: true, disabled: false }); // 'button button--active'
+ */
+export declare function block(baseName: string, additionalClasses: string[]): string;
+export declare function block(baseName: string, modifiers?: Modifier, additionalClasses?: string[]): string;

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

@@ -0,0 +1,26 @@
+import classnames from 'classnames';
+import { modifier } from './modifier.js';
+
+function block(baseName, modifiersOrAdditionalClasses, additionalClasses) {
+    let modifiers;
+    let classes;
+    if (Array.isArray(modifiersOrAdditionalClasses)) {
+        classes = modifiersOrAdditionalClasses;
+    }
+    else {
+        modifiers = modifiersOrAdditionalClasses;
+        classes = additionalClasses;
+    }
+    if (!modifiers && !classes) {
+        return baseName;
+    }
+    return classnames(
+    // Additional classes
+    classes, 
+    // Base class
+    baseName, 
+    // Modifier(s)
+    modifiers ? modifier(baseName, modifiers) : null);
+}
+
+export { block };

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

@@ -0,0 +1,16 @@
+import type { Modifier } from './modifier';
+/**
+ * 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')
+ * @param elem       The BEM element name (e.g., 'icon', 'title')
+ * @param modifier   Optional BEM modifier ()
+ * @returns combined BEM element class name
+ *
+ * @example
+ * element('my-button', 'icon'); // 'my-button__icon'
+ * element('my-button', 'icon', { active: true }); // 'my-button__icon my-button__icon--active'
+ */
+export declare function element(baseClass: string, elem: string, additionalClasses: string[]): string;
+export declare function element(baseClass: string, elem: string, modifiers?: Modifier, additionalClasses?: string[]): string;

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

@@ -0,0 +1,10 @@
+import { block } from './block.js';
+
+function element(baseClass, elem, modifiersOrAdditionalClasses, additionalClasses) {
+    if (Array.isArray(modifiersOrAdditionalClasses)) {
+        return block(`${baseClass}__${elem}`, modifiersOrAdditionalClasses);
+    }
+    return block(`${baseClass}__${elem}`, modifiersOrAdditionalClasses, additionalClasses);
+}
+
+export { element };

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

@@ -0,0 +1,18 @@
+import { block } from './block';
+import { element } from './element';
+import { type Modifier } from './modifier';
+/**
+ * Setup BEM block & element generation for a given base name.
+ */
+export declare function bem(baseName: string): {
+    block: {
+        (additionalClasses: string[]): string;
+        (modifiers?: Modifier, additionalClasses?: string[]): string;
+    };
+    element: {
+        (elem: string, additionalClasses: string[]): string;
+        (elem: string, modifiers?: Modifier, additionalClasses?: string[]): string;
+    };
+    modifier: (modifiers: Modifier) => string;
+};
+export { block, element };

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

@@ -0,0 +1,28 @@
+import { block } from './block.js';
+import { element } from './element.js';
+import { modifier } from './modifier.js';
+
+/**
+ * Setup BEM block & element generation for a given base name.
+ */
+function bem(baseName) {
+    function blockFn(modifiersOrAdditionalClasses, additionalClasses) {
+        if (Array.isArray(modifiersOrAdditionalClasses)) {
+            return block(baseName, modifiersOrAdditionalClasses);
+        }
+        return block(baseName, modifiersOrAdditionalClasses, additionalClasses);
+    }
+    function elementFn(elem, modifiersOrAdditionalClasses, additionalClasses) {
+        if (Array.isArray(modifiersOrAdditionalClasses)) {
+            return element(baseName, elem, modifiersOrAdditionalClasses);
+        }
+        return element(baseName, elem, modifiersOrAdditionalClasses, additionalClasses);
+    }
+    return {
+        block: blockFn,
+        element: elementFn,
+        modifier: (modifiers) => modifier(baseName, modifiers),
+    };
+}
+
+export { bem, block, element };

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

@@ -0,0 +1,17 @@
+/**
+ * Modifier
+ * @example { 'is-disabled': true, 'is-selected': false }
+ */
+export type Modifier = Record<string, boolean | undefined | null>;
+/**
+ * Generates BEM modifier class names.
+ *
+ * @param baseName   The base BEM class to attach modifiers to.
+ * @param modifiers  Map of modifier names to boolean values.
+ * @returns Combined modifier class names string.
+ *
+ * @example
+ * modifier('button', { active: true }); // 'button--active'
+ * modifier('button', { active: true, disabled: false }); // 'button--active'
+ */
+export declare function modifier(baseName: string, modifiers: Modifier): string;

package/js/utils/classNames/bem/modifier.js

@@ -0,0 +1,21 @@
+/**
+ * Generates BEM modifier class names.
+ *
+ * @param baseName   The base BEM class to attach modifiers to.
+ * @param modifiers  Map of modifier names to boolean values.
+ * @returns Combined modifier class names string.
+ *
+ * @example
+ * modifier('button', { active: true }); // 'button--active'
+ * modifier('button', { active: true, disabled: false }); // 'button--active'
+ */
+function modifier(baseName, modifiers) {
+    const modifierClasses = [];
+    for (const [key, value] of Object.entries(modifiers)) {
+        if (value)
+            modifierClasses.push(`${baseName}--${key}`);
+    }
+    return modifierClasses.join(' ');
+}
+
+export { modifier };

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

@@ -3,3 +3,4 @@ export * from './color';
 export * from './typography';
 export * from './spacing';
 export * from './visually-hidden';
+export { bem } from './bem';

package/js/utils/classNames/index.js

@@ -3,3 +3,4 @@ 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';
+export { bem } from './bem/index.js';

package/js/utils/index.d.ts

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

package/js/utils/index.js

@@ -2,3 +2,5 @@ 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';
+export { getWithSelector } from './selectors/getWithSelector.js';
+export { groupBySelector } from './selectors/groupBySelector.js';

package/js/utils/selectors/getWithSelector.d.ts

@@ -0,0 +1,3 @@
+import { Selector } from '../../types';
+/** Get value with a string of function selector */
+export declare const getWithSelector: <TObject, TValue>(selector: Selector<TObject, TValue> | undefined, object: TObject) => TValue;

package/js/utils/selectors/getWithSelector.js

@@ -0,0 +1,14 @@
+/** Get value with a string of function selector */
+const getWithSelector = (selector, object) => {
+    // Use the provided selector function
+    if (typeof selector === 'function') {
+        return selector(object);
+    }
+    // Use the provided selector as a property name
+    if (typeof selector === 'string') {
+        return object[selector];
+    }
+    return String(object);
+};
+
+export { getWithSelector };

package/js/utils/selectors/groupBySelector.d.ts

@@ -0,0 +1,6 @@
+import { Selector } from '../../types';
+/**
+ * Equivalent to `lodash/groupBy` but returns a `Map` of groups items (instead of an object)
+ * (has the major advantage to not forcing the keys to be string!)
+ */
+export declare function groupBySelector<TObject, TValue>(array: TObject[], selector: Selector<TObject, TValue>): Map<TValue, TObject[]>;

package/js/utils/selectors/groupBySelector.js

@@ -0,0 +1,21 @@
+import { getWithSelector } from './getWithSelector.js';
+
+/**
+ * Equivalent to `lodash/groupBy` but returns a `Map` of groups items (instead of an object)
+ * (has the major advantage to not forcing the keys to be string!)
+ */
+function groupBySelector(array, selector) {
+    const groups = new Map();
+    for (const item of array) {
+        const key = getWithSelector(selector, item);
+        let group = groups.get(key);
+        if (!group) {
+            group = [];
+            groups.set(key, group);
+        }
+        group.push(item);
+    }
+    return groups;
+}
+
+export { groupBySelector };

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

@@ -0,0 +1,2 @@
+export * from './getWithSelector';
+export * from './groupBySelector';

package/js/utils/selectors/index.js

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

package/package.json

@@ -6,7 +6,7 @@
         "url": "https://github.com/lumapps/design-system/issues"
     },
     "dependencies": {
-        "@lumx/icons": "^4.2.0",
+        "@lumx/icons": "^4.2.1-alpha.1",
         "classnames": "^2.3.2",
         "focus-visible": "^5.0.2",
         "lodash": "4.17.23",
@@ -32,12 +32,12 @@
     "scripts": {
         "generate:design-tokens": "yarn node style-dictionary/index.cjs",
         "build": "rollup -c",
-        "test": "vitest run",
+        "test": "vitest run --run",
         "type-check": "yarn tsc -p tsconfig.json",
         "update-version-changelog": "yarn version-changelog ../../CHANGELOG.md"
     },
     "sideEffects": false,
-    "version": "4.2.0",
+    "version": "4.2.1-alpha.1",
     "devDependencies": {
         "@rollup/plugin-typescript": "^12.3.0",
         "@testing-library/dom": "^10.4.1",
@@ -60,5 +60,6 @@
         "vite": "^7.3.1",
         "vite-tsconfig-paths": "^5.1.4",
         "vitest": "^4.0.18"
-    }
+    },
+    "stableVersion": "4.2.0"
 }

package/js/utils/_internal/className/getBasicClass.d.ts

@@ -1,13 +0,0 @@
-/**
- * Get the basic CSS class for the given type.
- *
- * @param  prefix The class name prefix for the generated CSS class.
- * @param  type   The type of CSS class we want to generate (e.g.: 'color', 'variant', ...).
- * @param  value  The value of the type of the CSS class (e.g.: 'primary', 'button', ...).
- * @return The basic CSS class.
- */
-export declare function getBasicClass({ prefix, type, value, }: {
-    prefix: string;
-    type: string;
-    value: string | number | boolean | undefined;
-}): string;

package/js/utils/_internal/className/handleBasicClasses.d.ts

@@ -1,15 +0,0 @@
-/**
- * Return all basic LumX CSS classes which are available for every components.
- *
- * @see {@link /src/components/index.d.ts} for the possible values of each parameter.
- *
- * @param  prefix The class name prefix for the generated CSS class.
- * @param  props  All the other props you want to generate a class.
- *                The rule of thumb: the key is the name of the prop in the class, the value a string that will
- *                be used in the classname to represent the value of the given prop.
- * @return All LumX basic CSS classes.
- */
-export declare function handleBasicClasses({ prefix, ...props }: {
-    prefix: string;
-    [prop: string]: any;
-}): string;

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

@@ -1,2 +0,0 @@
-export { handleBasicClasses } from './handleBasicClasses';
-export { getBasicClass } from './getBasicClass';