@muraldevkit/ui-toolkit 4.67.0 → 4.68.0-dev-5W5E.1

package/dist/types/hooks/useHasFocusableDescendant/index.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+/**
+ * Tracks whether the subtree of the given ref contains at least one element
+ * that participates in sequential focus navigation.
+ *
+ * Used by scrollable wrapper components (`MrlPanel`, `MrlModalContent`) to
+ * decide whether the wrapper itself needs `tabindex="0"`. Per ACT rule
+ * 0ssw9k (https://www.w3.org/WAI/standards-guidelines/act/rules/0ssw9k/) a
+ * scrollable region passes WCAG 2.1.1 Keyboard either by being focusable
+ * itself or by having a focusable descendant. When focusable descendants
+ * already exist, adding `tabindex="0"` to the wrapper produces a
+ * "meaningless tab stop" finding from manual auditors.
+ *
+ * The default return value is `true` so that, on the very first render
+ * (before the layout effect has measured the DOM), components err on the
+ * side of NOT adding a tab stop. The MutationObserver flips it to `false`
+ * synchronously inside the layout effect if the wrapper is genuinely
+ * empty of focusable descendants.
+ *
+ * @param {React.RefObject<HTMLElement | null>} ref - Ref pointing at the container whose subtree should be observed.
+ * @returns {boolean} `true` while the subtree contains at least one focusable element, `false` otherwise.
+ */
+export declare function useHasFocusableDescendant(ref: React.RefObject<HTMLElement | null>): boolean;

package/dist/types/hooks/useScrollbarInfo/index.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+export type ScrollbarInfo = {
+    /** Indicates if a horizontal scrollbar is present */
+    hasHorizontalScrollbar: boolean;
+    /** Indicates if a vertical scrollbar is present */
+    hasVerticalScrollbar: boolean;
+    /** Width in pixels of the vertical scrollbar (0 for overlay scrollbars) */
+    verticalScrollbarWidth: number;
+    /** Height in pixels of the horizontal scrollbar (0 for overlay scrollbars) */
+    horizontalScrollbarHeight: number;
+};
+/**
+ * Return type for the `useScrollbarInfo` hook.
+ */
+export type UseScrollbarInfoReturn<T extends HTMLElement> = ScrollbarInfo & {
+    scrollableContainerRef: React.MutableRefObject<T | null>;
+};
+/**
+ * Custom hook that provides information about the presence and dimensions of vertical and horizontal scrollbars
+ * in a scrollable container.
+ *
+ * @returns {UseScrollbarInfoReturn} Returns the scrollbar information and a ref to attach to the scrollable container
+ */
+export declare function useScrollbarInfo<T extends HTMLElement>(): UseScrollbarInfoReturn<T>;

package/dist/types/hooks/useTriggerPosition/constants.d.ts

@@ -0,0 +1,11 @@
+import { MenuPosition, MenuAlignment, CustomMenuPosition } from '../../components/menu/constants';
+export interface Alignment {
+    align: MenuAlignment;
+    position: MenuPosition;
+    customPosition?: CustomMenuPosition;
+}
+export interface Position {
+    top: number;
+    left: number;
+    flipped: boolean;
+}

package/dist/types/hooks/useTriggerPosition/index.d.ts

@@ -0,0 +1,17 @@
+import { RefObject } from 'react';
+import { Alignment, Position } from './constants';
+/**
+ * useTriggerPosition hook.
+ *
+ * Calculates the position of a menu element based on the alignment settings relative to a trigger element.
+ *
+ * @param triggerRef - Reference to the DOM element that triggers the menu.
+ * @param elementRef - Reference to the DOM element that is the menu.
+ * @param menuAlign - The alignment configuration of the menu.
+ * @param isElementVisible - Tells the hook if the element is visible. If false, the hook will not calculate the position.
+ * @param menuOffset - The offset of the menu from the trigger element.
+ * @param disable - Whether to disable the hook.
+ * @param disableFlipping - Whether to disable flipping logic when the menu overflows the screen.
+ * @returns {Position} The calculated position of the menu element.
+ */
+export declare const useTriggerPosition: (triggerRef: RefObject<HTMLElement> | undefined, elementRef: RefObject<HTMLElement>, menuAlign: Alignment, isElementVisible?: boolean, menuOffset?: number, disable?: boolean, disableFlipping?: boolean) => Position;

package/dist/types/hooks/useTriggerPosition/utilities.d.ts

@@ -0,0 +1,12 @@
+import { Alignment, Position } from './constants';
+/**
+ * Calculates the position of the menu based on alignment and viewport constraints.
+ *
+ * @param {Alignment} menuAlign - The alignment configuration for the menu.
+ * @param {number} offset - The offset distance between the menu and the trigger.
+ * @param {DOMRect} elementRect - The bounding rectangle of the menu element.
+ * @param {DOMRect} [triggerRect] - The bounding rectangle of the trigger element.
+ * @param {boolean} [disableFlipping] - If true, prevents flipping to the opposite side when overflowing.
+ * @returns {Position} The calculated position of the menu.
+ */
+export declare const getPosition: (menuAlign: Alignment, offset: number, elementRect: DOMRect, triggerRect?: DOMRect, disableFlipping?: boolean) => Position;

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './components';
+export * from './utils';
+export * from './contexts';
+export * from './hooks';

package/dist/types/utils/checkInvalidAttributes/index.d.ts

@@ -0,0 +1,7 @@
+import { AttrsObject } from '../setAttributes';
+/**
+ * Checks attrs object for invalid properties and provides a warning
+ *
+ * @param {AttrsObject} attrs - attrs object from a component
+ */
+export declare const checkInvalidAttributes: (attrs: AttrsObject | undefined) => void;

package/dist/types/utils/commonProps/index.d.ts

@@ -0,0 +1,20 @@
+import { AttrsObject } from '../setAttributes';
+/**
+ * These common props are used available on all UI Toolkit components.
+ */
+export interface MrlComponentProps {
+    /**
+     * Applies additional HTML attributes to the `svg` element.
+     * When using in a framework wrapper (e.g., React), treat it as an object and don't stringify.
+     * Otherwise, the value object needs to be stringified to not receive `"[Object object]"`.
+     * Example: `attrs='{ "data-foo": "bar" }'`
+     *
+     * @deprecated - `attrs` will be removed in favor of using HTML Attributes directly on components. Please update your usage accordingly.
+     */
+    attrs?: AttrsObject;
+    /**
+     * A object of CSS properties. Please use style sparingly, and only in cases where your
+     * needs can not be met by passing a class to the component.
+     */
+    style?: Record<string, unknown>;
+}

package/dist/types/utils/dataQa/index.d.ts

@@ -0,0 +1,6 @@
+export interface DataQa {
+    /**
+     * optional data-qa attribute for testing purposes.
+     */
+    ['data-qa']?: string;
+}

package/dist/types/utils/findAdjacentInteractiveElement/findAdjacentInteractiveElement.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Find the interactive element immediately before or after a reference element
+ *
+ * @param ref - The reference element
+ * @param direction - The direction to search in
+ * @returns The interactive element or null if none is found
+ */
+export declare const findAdjacentInteractiveElement: (ref: React.RefObject<HTMLElement> | undefined, direction?: 'next' | 'previous') => HTMLElement | null;

package/dist/types/utils/findAdjacentInteractiveElement/index.d.ts

@@ -0,0 +1 @@
+export * from './findAdjacentInteractiveElement';

package/dist/types/utils/frameDebounce/index.d.ts

@@ -0,0 +1,22 @@
+export interface FrameDebounceType {
+    debounce(callback: () => void): void;
+    cancel(): void;
+}
+/**
+ * @description Creates a wrapper for request animation frame that helps a little with performance this helps us only animate current frame reducing in jumps/tearing on slow devices.
+ */
+export declare const FrameDebounce: {
+    new (): {
+        frame: null | number;
+        /**
+         * debounce a callback wrapped in animation frame.
+         *
+         * @param callback callback to call after frame runs
+         */
+        debounce: (callback: () => void) => void;
+        /**
+         * cancel our frame.
+         */
+        cancel: () => void;
+    };
+};

package/dist/types/utils/getCamelCase/getCamelCase.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Takes a string and returns a camelCase version of the string
+ *
+ * @param {string} str - a string to set to camelCase
+ * @returns {string} - a string with special characters spaces removed, where words after a space are Uppercase leading
+ */
+export declare const getCamelCase: (str: string) => string;

package/dist/types/utils/getCamelCase/getCamelCase.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/utils/getCamelCase/index.d.ts

@@ -0,0 +1,2 @@
+import { getCamelCase } from './getCamelCase';
+export { getCamelCase };

package/dist/types/utils/getScrollableContainer/getScrollableContainer.d.ts

@@ -0,0 +1,10 @@
+export type ScrollAxis = 'vertical' | 'horizontal' | undefined;
+/**
+ * Get the scrollable container of an element.
+ *
+ * @param element - The element whose scrollable ancestor is needed.
+ * @param axis - Axis to check for scrollability ('vertical' | 'horizontal' | 'both' | 'all'). Defaults to 'vertical'.
+ * @param requireOverflow - When true, element must actually overflow on the axis; when false, only scroll styles are considered. Defaults to false.
+ * @returns The scrollable container for the specified axis.
+ */
+export declare const getScrollableContainer: (element: HTMLElement, axis?: ScrollAxis, requireOverflow?: boolean) => HTMLElement;

package/dist/types/utils/getScrollableContainer/index.d.ts

@@ -0,0 +1 @@
+export * from './getScrollableContainer';

package/dist/types/utils/hasHorizontalScroll/hasHorizontalScroll.d.ts

@@ -0,0 +1,11 @@
+export type HasHorizontalScrollReturn = {
+    hasScrollLeft: boolean;
+    hasScrollRight: boolean;
+};
+/**
+ * Test if an element has scrollable content in the horizontal axis
+ *
+ * @param element - the element that is scrollable
+ * @returns - object with hasScrollLeft and hasScrollRight properties
+ */
+export declare const hasHorizontalScroll: (element: HTMLElement) => HasHorizontalScrollReturn;

package/dist/types/utils/hasHorizontalScroll/index.d.ts

@@ -0,0 +1 @@
+export * from './hasHorizontalScroll';

package/dist/types/utils/hasScrollContent/hasScrollContent.d.ts

@@ -0,0 +1,11 @@
+export type HasScrollContentReturn = {
+    hasScrollTop: boolean;
+    hasScrollBottom: boolean;
+};
+/**
+ * Test if an element has scrollable content left
+ *
+ * @param {HTMLElement} element - the element you want to test
+ * @returns {HasScrollContentReturn} - object with hasScrollTop and hasScrollBottom properties
+ */
+export declare const hasScrollContent: (element: HTMLElement) => HasScrollContentReturn;

package/dist/types/utils/hasScrollContent/index.d.ts

@@ -0,0 +1 @@
+export * from './hasScrollContent';

package/dist/types/utils/index.d.ts

@@ -0,0 +1,16 @@
+export * from './commonProps';
+export * from './findAdjacentInteractiveElement';
+export * from './hasHorizontalScroll';
+export * from './hasScrollContent';
+export * from './isElementScrollable';
+export * from './getCamelCase';
+export * from './getScrollableContainer';
+export * from './isImagePath';
+export * from './isImageUri';
+export * from './isObject';
+export * from './isElementAriaDisabled';
+export * from './setAttributes';
+export * from './noop';
+export * from './preventDefault';
+export * from './trapFocus';
+export * from './layers';

package/dist/types/utils/isElementAriaDisabled/index.d.ts

@@ -0,0 +1 @@
+export * from './isElementAriaDisabled';

package/dist/types/utils/isElementAriaDisabled/isElementAriaDisabled.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Checks if an element has aria-disabled="true"
+ *
+ * @param {HTMLElement | null | undefined} element - The element to check for aria-disabled attribute
+ * @returns {boolean} - true if the element has aria-disabled="true", false otherwise
+ */
+export declare const isElementAriaDisabled: (element: HTMLElement | null | undefined) => boolean;

package/dist/types/utils/isElementAriaDisabled/isElementAriaDisabled.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/utils/isElementScrollable/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Test if an element is scrollable
+ *
+ * @param {HTMLElement} element - the element you want to test
+ * @returns {boolean} - true if the element is scrollable, false if it is not scrollable
+ */
+export declare const isElementScrollable: (element: HTMLElement) => boolean;

package/dist/types/utils/isImagePath/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Checks if a passed image string is a valid URL
+ *
+ * @param {string} image - the image string being tested
+ * @returns {boolean} - if the image is an image URL
+ */
+export declare const isImagePath: (image: string) => image is string;

package/dist/types/utils/isImageUri/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Checks if a passed image string is an image URI
+ *
+ * @param {string} image - the image string being tested
+ * @returns {boolean} - if the image is an image URI
+ */
+export declare const isImageUri: (image: string) => image is string;

package/dist/types/utils/isObject/index.d.ts

@@ -0,0 +1,2 @@
+import { Item, isObject } from "./isObject";
+export { type Item, isObject };

package/dist/types/utils/isObject/isObject.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Item is passed to the `isObject` function.
+ * Since we want to be able to check if anything is an object, we allow
+ * anything to be passed to the function.
+ */
+export type Item = unknown;
+/**
+ * Tests that a variable is actually an object and not an array  or null
+ * which can mistakenly be flagged as an object
+ *
+ * @param {Item} item - variable to tests
+ * @returns {boolean} - value if item is actually an Object
+ */
+export declare const isObject: (item: Item) => boolean;

package/dist/types/utils/isObject/isObject.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/utils/isTouch/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Check if the device is a touch device
+ *
+ * @returns {boolean} - True if the device is a touch device
+ */
+export declare const isTouchDevice: () => boolean;

package/dist/types/utils/layers/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * References to the different portal layers
+ */
+export declare const PORTAL_LAYERS: {
+    readonly ROOT: {
+        readonly name: "mrl-root-portal";
+        readonly zIndex: 50000;
+    };
+    readonly TOAST: {
+        readonly name: "mrl-toast-portal";
+        readonly zIndex: 50001;
+    };
+    readonly MENU: {
+        readonly name: "mrl-menu-portal";
+        readonly zIndex: 50002;
+    };
+    readonly POPOVER: {
+        readonly name: "mrl-popover-portal";
+        readonly zIndex: 50003;
+    };
+    readonly POPOVER_MENU: {
+        readonly name: "mrl-popover-menu-portal";
+        readonly zIndex: 50004;
+    };
+    readonly CALLOUT: {
+        readonly name: "mrl-callout-portal";
+        readonly zIndex: 50004;
+    };
+    readonly MODAL: {
+        readonly name: "mrl-modal";
+        readonly zIndex: 50005;
+    };
+    readonly SELECT: {
+        readonly name: "mrl-select-portal";
+        readonly zIndex: 50006;
+    };
+    readonly TOOLTIP: {
+        readonly name: "mrl-tooltip-portal";
+        readonly zIndex: 50007;
+    };
+    readonly TOP: {
+        readonly name: "mrl-top-portal";
+        readonly zIndex: 50008;
+    };
+};
+/**
+ * Get the current portal layer based on the provided element
+ *
+ * @param element - the element to check for the closest portal layer
+ * @returns the portal layer id
+ */
+export declare const getCurrentPortalLayer: (element: HTMLElement) => string | null;

package/dist/types/utils/noop/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * No operation function to be used as a default callback.
+ *
+ * Example usage: in tests where there is a required handler, but we do not want to do anything.
+ * Better than passing a console log which clutters up our test output.
+ */
+export declare const noop: () => void;

package/dist/types/utils/preventDefault/index.d.ts

@@ -0,0 +1 @@
+export * from './preventDefault';

package/dist/types/utils/preventDefault/preventDefault.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Prevent default on event
+ *
+ * @param e - The event
+ */
+export declare const preventDefault: (e: React.MouseEvent | React.KeyboardEvent | MouseEvent | KeyboardEvent) => void;

package/dist/types/utils/setAttributes/index.d.ts

@@ -0,0 +1,2 @@
+import { AttrsObject, ClassObject, getUniqueId, setAttributes, setClasses } from './setAttributes';
+export { type AttrsObject, type ClassObject, getUniqueId, setAttributes, setClasses };

package/dist/types/utils/setAttributes/setAttributes.d.ts

@@ -0,0 +1,35 @@
+export type AttrsObject = Record<string, any>;
+/**
+ * Object that contains all of the classes that can be applied to an element
+ * and a condition that determines if that instance should have it
+ * applied or not. The structure is:
+ * "my-class": !theConditional
+ */
+export type ClassObject = Record<string, boolean>;
+/**
+ * Sets up a classObject to be used by the className prop
+ *
+ * @todo - 2563 - use setClasses across components
+ * @param {string} customClasses - custom classes to apply via the attrs prop
+ * @param {ClassObject} defaultClasses - design system component classes to apply
+ * @returns {ClassObject} - with all classes
+ */
+export declare const setClasses: (customClasses: AttrsObject | undefined, defaultClasses: ClassObject) => ClassObject;
+/**
+ * Set an object of attributes to be used in a given component.
+ *
+ * @param {AttrsObject} attributes - The custom attributes passed to the component
+ * @param {AttrsObject} defaults - An optional object of the default attributes of a component
+ * @param {string} className - Default classes to apply to the component
+ *
+ * Use when applying attributes such as a className directly to a react component.
+ * @returns {AttrsObject} - An object of component attributes
+ */
+export declare const setAttributes: (attributes: AttrsObject | undefined, defaults?: AttrsObject, className?: string) => AttrsObject;
+/**
+ *  Generates unique identifier
+ *
+ * @param {string} prefix  - prefix for identifier
+ * @returns {string} - prefixed unique identifier
+ */
+export declare const getUniqueId: (prefix?: string) => string;

package/dist/types/utils/setAttributes/setAttributes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/utils/trapFocus/index.d.ts

@@ -0,0 +1,22 @@
+export declare const FOCUSABLE_ELEMENTS_SELECTOR: string;
+/**
+ * Focus trap logic
+ * @param {HTMLElement} element - The component props.
+ * @returns {HTMLElement[]} - The focusable elements inside the element.
+ */
+export declare const getFocusableElementsInsideElement: (element: HTMLElement) => HTMLElement[];
+/**
+ * Gets the first element with the data-autofocus="true" attribute within the container element
+ * @param {HTMLElement} containerElement - container element
+ * @returns {HTMLElement | undefined} - the first element that has autofocus="true" or undefined
+ */
+export declare const getElementWithAutofocus: (containerElement: HTMLElement) => HTMLElement | undefined;
+/**
+ * Traps focus inside of an element
+ * Adapted from https://hidde.blog/using-javascript-to-trap-focus-in-an-element/
+ * @param {HTMLElement} element // Element to trap focus in
+ * @param {boolean} disableAutofocus // Whether to disable autofocus
+ * @returns {Function}          // Cleanup function to be run when component is
+ *                              // removed from the DOM
+ */
+export declare const trapFocus: (element: HTMLElement, disableAutofocus?: boolean) => (() => void);

package/package.json

@@ -1,17 +1,24 @@
 {
 	"name": "@muraldevkit/ui-toolkit",
-	"version": "4.67.0",
+	"version": "4.68.0-dev-5W5E.1",
 	"description": "Mural's UI Toolkit",
-	"main": "./dist/index.js",
-	"module": "./dist/index.js",
-	"types": "./dist/index.d.ts",
+	"main": "./dist/cjs/index.js",
+	"module": "./dist/esm/index.js",
+	"types": "./dist/types/index.d.ts",
+	"sideEffects": [
+		"**/*.scss",
+		"**/*.css"
+	],
 	"files": [
 		"dist"
 	],
 	"scripts": {
 		"prebuild": "rimraf dist",
-		"analyze": "webpack --mode=production --analyze",
-		"build": "webpack --mode=production",
+		"analyze": "ANALYZE=true rollup --config rollup.config.mjs",
+		"build": "npm run build:js && npm run build:css && npm run build:types",
+		"build:css": "webpack --mode=production",
+		"build:js": "rollup --config rollup.config.mjs",
+		"build:types": "tsc --project tsconfig.build.json",
 		"compile": "storybook build",
 		"dev": "storybook dev -p 6006",
 		"dev:dev-tools": "DEV_TOOLS=true storybook dev -p 6006",
@@ -56,6 +63,9 @@
 		"@muraldevkit/ds-icons": "*",
 		"@muraldevkit/ds-icons-animated": "*",
 		"@muraldevkit/ds-pictograms": "*",
+		"@rollup/plugin-babel": "6.0.4",
+		"@rollup/plugin-commonjs": "28.0.6",
+		"@rollup/plugin-node-resolve": "16.0.1",
 		"@storybook/addon-a11y": "10.4.6",
 		"@storybook/addon-docs": "10.4.6",
 		"@storybook/addon-links": "10.4.6",
@@ -68,6 +78,7 @@
 		"@types/classnames": "2.2.5",
 		"@types/jest": "29.5.1",
 		"@types/lodash.debounce": "4.0.7",
+		"@types/lodash.uniqueid": "4.0.9",
 		"@types/path-browserify": "1.0.2",
 		"@types/react": "18.2.22",
 		"@types/react-dom": "18.2.7",
@@ -97,6 +108,9 @@
 		"prettier": "3.6.2",
 		"react-markdown": "8.0.7",
 		"rimraf": "6.1.0",
+		"rollup": "4.62.2",
+		"rollup-plugin-postcss": "4.0.2",
+		"rollup-plugin-visualizer": "5.14.0",
 		"sass": "1.62.1",
 		"sass-loader": "13.2.2",
 		"semantic-release": "22.0.12",
@@ -120,6 +134,7 @@
 		"@tanstack/react-virtual": "3.13.13",
 		"classnames": "2.5.1",
 		"lodash.debounce": "4.0.8",
+		"lodash.uniqueid": "4.0.1",
 		"path-browserify": "1.0.1",
 		"react": "18.2.0",
 		"react-dom": "18.2.0",

package/dist/index.js.LICENSE.txt

@@ -1,8 +0,0 @@
-/**
- * @license
- * Lodash <https://lodash.com/>
- * Copyright OpenJS Foundation and other contributors <https://openjsf.org/>
- * Released under MIT license <https://lodash.com/license>
- * Based on Underscore.js 1.8.3 <http://underscorejs.org/LICENSE>
- * Copyright Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors
- */