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

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

@@ -1,73 +0,0 @@
-import classnames from 'classnames';
-import { Size } from '../../../constants/enums/index.js';
-import '../../../constants/browser/index.js';
-
-/** Set of valid AbstractSize values for runtime detection. */
-const ABSTRACT_SIZES = new Set([Size.tiny, Size.regular, Size.medium, Size.big, Size.huge]);
-function isAbstractSize(value) {
-    return typeof value === 'string' && ABSTRACT_SIZES.has(value);
-}
-function spacing(type, directionOrSize, size) {
-    // Resolve shorthand: spacing(type, size) => spacing(type, undefined, size)
-    const isShorthand = isAbstractSize(directionOrSize) || (directionOrSize === null && size === undefined);
-    const direction = isShorthand ? undefined : directionOrSize ?? undefined;
-    const resolvedSize = isShorthand ? directionOrSize : size;
-    let baseClass = `lumx-spacing-${type}`;
-    if (direction && direction !== 'all') {
-        baseClass = `${baseClass}-${direction}`;
-    }
-    if (resolvedSize) {
-        baseClass = `${baseClass}-${resolvedSize}`;
-    }
-    else if (resolvedSize === 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)));
-function margin(directionOrSize, size) {
-    if (isAbstractSize(directionOrSize) || (directionOrSize === null && size === undefined)) {
-        return spacing('margin', directionOrSize);
-    }
-    return spacing('margin', directionOrSize ?? undefined, 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 })));
-function padding(directionOrSize, size) {
-    if (isAbstractSize(directionOrSize) || (directionOrSize === null && size === undefined)) {
-        return spacing('padding', directionOrSize);
-    }
-    return spacing('padding', directionOrSize ?? undefined, 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

@@ -1,6 +0,0 @@
-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

@@ -1,9 +0,0 @@
-/**
- * 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

@@ -1,5 +0,0 @@
-/**
- * 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

@@ -1,11 +0,0 @@
-import '../../../constants/enums/index.js';
-import { VISUALLY_HIDDEN } from '../../../constants/className/index.js';
-import '../../../constants/browser/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/events/index.d.ts

@@ -1,2 +0,0 @@
-export * from './keyboard';
-export * from './swipe';

package/js/utils/events/keyboard.js

@@ -1,44 +0,0 @@
-/**
- * Make sure the pressed key is the enter key before calling the callback.
- *
- * @param  handler The handler to call on enter/return press.
- * @return The decorated function.
- */
-function onEnterPressed(handler) {
-    return (evt) => {
-        if (evt.key !== 'Enter') {
-            return;
-        }
-        handler(evt);
-    };
-}
-/**
- * Make sure the pressed key is the escape key before calling the callback.
- *
- * @param  handler The handler to call on enter/return press.
- * @return The decorated function.
- */
-function onEscapePressed(handler) {
-    return (evt) => {
-        if (evt.key !== 'Escape') {
-            return;
-        }
-        handler(evt);
-    };
-}
-/**
- * Handle button key pressed (Enter + Space).
- *
- * @param  handler The handler to call.
- * @return The decorated function.
- */
-function onButtonPressed(handler) {
-    return (evt) => {
-        if (evt.key !== 'Enter' && evt.key !== ' ') {
-            return;
-        }
-        handler(evt);
-    };
-}
-
-export { onButtonPressed, onEnterPressed, onEscapePressed };

package/js/utils/events/swipe.js

@@ -1,79 +0,0 @@
-/**
- * Checks whether the browser support passive events.
- * @see https://github.com/Modernizr/Modernizr/blob/6d56d814b9682843313b16060adb25a58d83a317/feature-detects/dom/passiveeventlisteners.js
- */
-function isPassiveEventAvailable() {
-    let supportsPassiveOption = false;
-    try {
-        const opts = Object.defineProperty({}, 'passive', {
-            get() {
-                supportsPassiveOption = true;
-            },
-        });
-        window.addEventListener('testPassiveEventSupport', () => { }, opts);
-        window.removeEventListener('testPassiveEventSupport', () => { }, opts);
-    }
-    catch (e) {
-        // ignored
-    }
-    return supportsPassiveOption;
-}
-/**
- * Detects horizontal swipe direction without blocking the browser scroll using passive event.
- * @see http://javascriptkit.com/javatutors/touchevents2.shtml
- * @see https://github.com/WICG/EventListenerOptions/blob/gh-pages/explainer.md
- */
-function detectHorizontalSwipe(touchSurface, handleSwipe) {
-    let startX;
-    let startY;
-    // Required min distance traveled to be considered swipe.
-    const threshold = 150;
-    // Maximum distance allowed at the same time in perpendicular direction.
-    const restraint = 150;
-    // Maximum time allowed to travel that distance.
-    const allowedTime = 300;
-    let elapsedTime;
-    let startTime;
-    let finished;
-    const onTouchStart = (evt) => {
-        const [touch] = Array.from(evt.changedTouches);
-        startX = touch.pageX;
-        startY = touch.pageY;
-        // Record time when finger first makes contact with surface.
-        startTime = new Date().getTime();
-        finished = false;
-    };
-    const onTouchMove = (evt) => {
-        if (finished) {
-            return;
-        }
-        elapsedTime = new Date().getTime() - startTime;
-        if (elapsedTime > allowedTime) {
-            // Touch swipe too long to be considered.
-            return;
-        }
-        const [touch] = Array.from(evt.changedTouches);
-        // Get horizontal dist traveled by finger while in contact with surface.
-        const distX = touch.pageX - startX;
-        // Get vertical dist traveled by finger while in contact with surface.
-        const distY = touch.pageY - startY;
-        if (!(Math.abs(distX) >= threshold && Math.abs(distY) <= restraint)) {
-            // Swipe is not horizontal.
-            return;
-        }
-        // Swipe direction.
-        const direction = distX < 0 ? 'left' : 'right';
-        handleSwipe(direction);
-        finished = true;
-    };
-    // Activate passive event if possible for better scrolling performance.
-    const eventOptions = isPassiveEventAvailable() ? { passive: true } : false;
-    touchSurface.addEventListener('touchstart', onTouchStart, eventOptions);
-    touchSurface.addEventListener('touchmove', onTouchMove, eventOptions);
-    return () => {
-        touchSurface.removeEventListener('touchstart', onTouchStart, eventOptions);
-        touchSurface.removeEventListener('touchmove', onTouchMove, eventOptions);
-    };
-}
-
-export { detectHorizontalSwipe };

package/js/utils/focus/constants.d.ts

@@ -1,10 +0,0 @@
-/** CSS selector listing all tabbable elements. */
-export declare const TABBABLE_ELEMENTS_SELECTOR = "a[href], button, textarea, input:not([type=\"hidden\"]):not([hidden]), [tabindex]";
-/**
- * CSS selector matching elements that should be excluded from focus traversal.
- *
- * Note: `aria-disabled` is intentionally NOT in this list — per ARIA semantics, an `aria-disabled` element
- * remains focusable (and discoverable by assistive tech). To remove an element from the tab order, use
- * `tabindex="-1"` instead.
- */
-export declare const DISABLED_SELECTOR = "[hidden], [tabindex=\"-1\"], [disabled]:not([disabled=\"false\"])";

package/js/utils/focus/getFirstAndLastFocusable.d.ts

@@ -1,13 +0,0 @@
-/**
- * Get first and last elements focusable in an element.
- *
- * @param parentElement The element in which to search focusable elements.
- * @return first and last focusable elements
- */
-export declare function getFirstAndLastFocusable(parentElement: HTMLElement | ShadowRoot): {
-    first: HTMLElement;
-    last: HTMLElement;
-} | {
-    first?: undefined;
-    last?: undefined;
-};

package/js/utils/focus/getFocusableElements.d.ts

@@ -1 +0,0 @@
-export declare function getFocusableElements(element: HTMLElement | ShadowRoot): HTMLElement[];

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

@@ -1,4 +0,0 @@
-export { getFirstAndLastFocusable } from './getFirstAndLastFocusable';
-export { getFocusableElements } from './getFocusableElements';
-export { setupFocusTrap, type SetupFocusTrapOptions } from './setupFocusTrap';
-export { TABBABLE_ELEMENTS_SELECTOR, DISABLED_SELECTOR } from './constants';

package/js/utils/focus/setupFocusTrap.d.ts

@@ -1,28 +0,0 @@
-export interface SetupFocusTrapOptions {
-    /** The element in which to trap the focus. */
-    focusZoneElement: HTMLElement;
-    /**
-     * The element to focus when the trap is activated.
-     * Falls back to the first focusable element inside the zone, then to the zone element itself.
-     */
-    focusElement?: HTMLElement | null;
-}
-/**
- * Trap 'Tab' focus switch inside the `focusZoneElement`.
- *
- * Setup behavior:
- * 1. Focus `focusElement` if provided and contained in the zone.
- * 2. Otherwise focus the first focusable descendant.
- * 3. Otherwise focus the zone element itself (falling back to setting `tabindex="-1"` if needed) so that
- *    keyboard users (especially screen reader users) land inside the trapped region (e.g. an empty dialog).
- *
- * Tab key behavior:
- * - With at least one focusable descendant: focus cycles between the first and last focusable in the zone.
- * - With no focusable descendant: Tab is swallowed and focus is restored to the zone element itself.
- *
- * Multiple traps stack — only the latest one is active; previous traps re-enable when the latest is torn down.
- *
- * @param options Trap configuration.
- * @param signal  AbortSignal used to tear down the trap.
- */
-export declare function setupFocusTrap(options: SetupFocusTrapOptions, signal: AbortSignal): void;

package/js/utils/focusNavigation/createActiveItemState.d.ts

@@ -1,26 +0,0 @@
-import type { FocusNavigationCallbacks } from './types';
-/**
- * Internal state for tracking the active (focused) item.
- * Shared by both list and grid navigation implementations.
- */
-export interface ActiveItemState {
-    /** Get the currently active item. */
-    readonly active: HTMLElement | null;
-    /** Set the active item (handles deactivate/activate callbacks). */
-    setActive(item: HTMLElement | null): void;
-    /** Clear the active item (deactivate + clear callbacks). */
-    clear(): void;
-}
-/**
- * Create shared active item state with cleanup on abort.
- *
- * Callback invocation:
- * - `setActive(item)`: calls `onDeactivate(previous)` then `onActivate(item)`.
- * - `clear()`: calls `onDeactivate(current)` then `onClear()`.
- * - On `signal.abort()`: same as `clear()`.
- *
- * @param callbacks Focus state change callbacks.
- * @param signal AbortSignal for cleanup.
- * @param initialItem Optional item to silently pre-select on creation (no callbacks fired).
- */
-export declare function createActiveItemState(callbacks: FocusNavigationCallbacks, signal: AbortSignal, initialItem?: HTMLElement | null): ActiveItemState;

package/js/utils/focusNavigation/createGridFocusNavigation.d.ts

@@ -1,16 +0,0 @@
-import type { FocusNavigationCallbacks, FocusNavigationController, GridNavigationOptions } from './types';
-/**
- * Create a focus navigation controller for a 2D grid.
- *
- * Resolves rows and cells by querying the DOM and commits focus by updating the
- * active-item state (which fires {@link FocusNavigationCallbacks}).
- *
- * Supports Up/Down between rows (with column memory) and Left/Right between cells
- * (with wrapping across rows).
- *
- * @param options Grid navigation options (container, rowSelector, cellSelector, wrap).
- * @param callbacks Callbacks for focus state changes.
- * @param signal AbortSignal for cleanup.
- * @returns FocusNavigationController instance.
- */
-export declare function createGridFocusNavigation(options: GridNavigationOptions, callbacks: FocusNavigationCallbacks, signal: AbortSignal): FocusNavigationController;

package/js/utils/focusNavigation/createListFocusNavigation.d.ts

@@ -1,15 +0,0 @@
-import type { FocusNavigationCallbacks, ListFocusNavigationController, ListNavigationOptions } from './types';
-/**
- * Create a focus navigation controller for a 1D list.
- *
- * This controller is **stateless** — it does not maintain an internal reference to
- * the active item. Instead it reads the active item from the DOM each time via the
- * `getActiveItem` callback provided in the options. This avoids any desync between
- * the controller's internal state and the actual DOM.
- *
- * @param options List navigation options (container, itemSelector, direction, wrap, getActiveItem).
- * @param callbacks Callbacks for focus state changes.
- * @param signal AbortSignal for cleanup.
- * @returns ListFocusNavigationController instance.
- */
-export declare function createListFocusNavigation(options: ListNavigationOptions, callbacks: FocusNavigationCallbacks, signal: AbortSignal): ListFocusNavigationController;

package/js/utils/focusNavigation/createPendingNavigation.d.ts

@@ -1,7 +0,0 @@
-/** Create a pending navigation store; discards intent on abort. */
-export declare function createPendingNavigation(signal: AbortSignal): {
-    readonly hasPending: boolean;
-    defer(navigate: () => boolean): void;
-    flush(): void;
-    clear: () => void;
-};

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

@@ -1,5 +0,0 @@
-export type { FocusNavigationCallbacks, FocusNavigationController, FocusNavigationSelectors, GridNavigationOptions, ListFocusNavigationController, ListFocusNavigationSelectors, ListNavigationOptions, } from './types';
-export type { RovingTabIndexOptions } from './setupRovingTabIndex';
-export { createListFocusNavigation } from './createListFocusNavigation';
-export { createGridFocusNavigation } from './createGridFocusNavigation';
-export { setupRovingTabIndex } from './setupRovingTabIndex';

package/js/utils/focusNavigation/setupRovingTabIndex.d.ts

@@ -1,37 +0,0 @@
-import type { FocusNavigationController } from './types';
-/** Options for {@link setupRovingTabIndex}. */
-export interface RovingTabIndexOptions {
-    /** Container element holding the focusable items. */
-    container: HTMLElement;
-    /** CSS selector identifying focusable items within the container. */
-    itemSelector: string;
-    /**
-     * Navigation axis — determines which arrow keys navigate.
-     * - `'horizontal'` (default): Left/Right navigate.
-     * - `'vertical'`: Up/Down navigate.
-     */
-    direction?: 'horizontal' | 'vertical';
-    /** CSS selector matching disabled items (skipped during navigation). */
-    itemDisabledSelector?: string;
-    /**
-     * Attribute name indicating the selected item (e.g. `'aria-selected'`, `'aria-checked'`).
-     * When set, the roving tabindex will observe changes to this attribute and keep
-     * `tabindex="0"` in sync with the item whose attribute value is `"true"`.
-     * Default: `'aria-selected'`.
-     */
-    itemSelectedAttr?: string;
-    /** Called when an item receives focus via keyboard navigation. */
-    onItemFocused?: (item: HTMLElement) => void;
-}
-/**
- * Set up the roving tabindex pattern on a container element.
- *
- * - Keyboard navigation (Arrow keys, Home, End)
- * - tabindex management (`0` on active, `-1` on others)
- * - Mount normalization (single-tabstop invariant)
- * - DOM mutation handling via MutationObserver:
- *   removal recovery, insertion normalization, disabled-state changes
- *
- * Torn down when `signal` is aborted.
- */
-export declare function setupRovingTabIndex(options: RovingTabIndexOptions, signal: AbortSignal): FocusNavigationController;

package/js/utils/focusNavigation/types.d.ts

@@ -1,68 +0,0 @@
-export interface FocusNavigationCallbacks {
-    onActivate(item: HTMLElement): void;
-    onDeactivate(item: HTMLElement): void;
-    onClear?(): void;
-}
-export interface ListNavigationOptions {
-    type: 'list';
-    container: HTMLElement;
-    itemSelector: string;
-    direction?: 'vertical' | 'horizontal';
-    wrap?: boolean;
-    itemDisabledSelector?: string;
-    getActiveItem?: () => HTMLElement | null;
-}
-export interface GridNavigationOptions {
-    type: 'grid';
-    container: HTMLElement;
-    rowSelector: string;
-    cellSelector: string;
-    wrap?: boolean;
-}
-/** Pure, side-effect-free selection layer for focus navigation. */
-export interface FocusNavigationSelectors {
-    readonly activeItem: HTMLElement | null;
-    readonly hasNavigableItems: boolean;
-    getFirst(): HTMLElement | null;
-    getLast(): HTMLElement | null;
-    getMatching(predicate: (item: HTMLElement) => boolean): HTMLElement | null;
-}
-/**
- * List-specific selection layer.
- * Adds {@link findNearestEnabled} and the combined enabled-item selector string.
- */
-export interface ListFocusNavigationSelectors extends FocusNavigationSelectors {
-    readonly enabledItemSelector: string;
-    findNearestEnabled(anchor: Node): HTMLElement | null;
-}
-/**
- * Focus navigation controller — the mover layer. Every method commits focus via
- * {@link FocusNavigationCallbacks}. The pure read layer lives behind {@link selectors}.
- *
- * To move focus to the first/last navigable item:
- * `goTo((s) => s.getFirst())` / `goTo((s) => s.getLast())`.
- */
-export interface FocusNavigationController<Selectors extends FocusNavigationSelectors = FocusNavigationSelectors> {
-    readonly type: 'list' | 'grid';
-    readonly selectors: Selectors;
-    goToOffset(offset: number): boolean;
-    clear(): void;
-    goUp(): boolean;
-    goDown(): boolean;
-    goLeft(): boolean;
-    goRight(): boolean;
-    /**
-     * Navigate via a resolver, deferring when the target is not yet in the DOM.
-     * ```ts
-     * nav.goTo((sel) => sel.getMatching(isSelected) ?? sel.getFirst());
-     * ```
-     */
-    goTo(resolve: (selectors: Selectors) => HTMLElement | null): boolean;
-    /**
-     * Replay the pending navigation intent stored by {@link goTo}.
-     * No-op when nothing is pending.
-     */
-    flushPendingNavigation(): void;
-}
-export interface ListFocusNavigationController extends FocusNavigationController<ListFocusNavigationSelectors> {
-}

package/js/utils/function/listenerTower.d.ts

@@ -1,13 +0,0 @@
-export type Listener = {
-    enable(): void;
-    disable(): void;
-};
-/**
- * Keep track of listeners, only the last registered listener gets activated at any point (previously registered
- * listener are disabled).
- * When a listener gets unregistered, the previously registered listener gets enabled again.
- */
-export declare function makeListenerTowerContext(): {
-    register(listener: Listener): void;
-    unregister(listener: Listener): void;
-};

package/js/utils/iterable/first.d.ts

@@ -1,2 +0,0 @@
-/** Return the first item of an iterable, or `null` if it is empty. */
-export declare function first<T>(iterable: Iterable<T>): T | null;

package/js/utils/locale/getCurrentLocale.d.ts

@@ -1,7 +0,0 @@
-/**
- * Get current browser locale (BCP-47 string).
- *
- * Reads `navigator.languages[0]` (the user's preferred language) with a
- * fallback to `navigator.language`.
- */
-export declare const getCurrentLocale: () => string;

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

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

package/js/utils/select/findOptionById.d.ts

@@ -1,13 +0,0 @@
-import type { Selector } from '../../types';
-/**
- * Find the option whose id matches the given value.
- *
- * Used by Select* wrappers to resolve a selection event (which carries the option id
- * as `selectedOption.value`) back to the original option object.
- *
- * @param options    The list of options.
- * @param getOptionId Selector returning the option id (matches `<Combobox.Option value>`).
- * @param id          The id to match against.
- * @return The matching option, or `undefined` if none is found / inputs are nullish.
- */
-export declare function findOptionById<O>(options: readonly O[] | undefined, getOptionId: Selector<O> | undefined, id: unknown): O | undefined;

package/js/utils/select/getOptionDisplayName.d.ts

@@ -1,8 +0,0 @@
-import type { Selector } from '../../types';
-/**
- * Get the display name for a single option value.
- *
- * Resolves the option's display name by trying `getOptionName` first,
- * then falling back to `getOptionId`, returning `''` for nullish values.
- */
-export declare function getOptionDisplayName<O>(value: O | undefined, getOptionName?: Selector<O, string | undefined | null>, getOptionId?: Selector<O>): string;

package/js/utils/select/renderSelectOptions.d.ts

@@ -1,7 +0,0 @@
-import type { JSXElement } from '../../types';
-import type { BaseSelectComponents, RenderSelectOptionsProps } from './types';
-/**
- * Render options as ComboboxOption elements.
- * Framework-specific components are passed as a second argument.
- */
-export declare function renderSelectOptions<O>(props: RenderSelectOptionsProps<O>, components: BaseSelectComponents): JSXElement;

package/js/utils/select/toggleSelection.d.ts

@@ -1,23 +0,0 @@
-import type { Selector } from '../../types';
-/**
- * Compute the next selection state after a user toggles an option.
- *
- * Single-mode behaviour (`isMultiple=false`):
- * - Returns the option matched by id (or `undefined` if none matches the id —
- *   e.g. when the consumer triggers a custom action via `beforeOptions`).
- *
- * Multi-mode behaviour (`isMultiple=true`):
- * - If the option is already in the current value array → returns a new array with it removed.
- * - Otherwise → returns a new array with the option appended.
- * - If the id matches no option in `options` (e.g. custom actions), the current array is returned unchanged.
- *
- * Pure function: never mutates `currentValue`.
- *
- * @param options          The list of options.
- * @param getOptionId      Selector returning the option id (matches `<Combobox.Option value>`).
- * @param currentValue     Current selection (option, array of options, or undefined).
- * @param selectedOptionId Id of the option the user just selected.
- * @param isMultiple       Whether to use multi-select semantics.
- * @return                 The new selection — `O | undefined` in single mode, `O[]` in multi mode.
- */
-export declare function toggleSelection<O>(options: readonly O[] | undefined, getOptionId: Selector<O> | undefined, currentValue: O | O[] | undefined, selectedOptionId: unknown, isMultiple: boolean): O | O[] | undefined;